WhatsApp MCP Server

Connect WhatsApp Business to Claude Code and Claude Desktop. Read, search, and send WhatsApp messages directly from Claude with end-to-end encryption.

How It Works

Your WhatsApp → VIDA AI Relay (encrypted) → MCP Server (local) → Your Neon DB
                  ↑                              ↓
           Only sees blobs              Decrypts with your
           Never plaintext              private key (local only)

Your messages are encrypted before they hit our servers. We store only encrypted blobs. Only your local MCP server can decrypt them using a private key that never leaves your machine.

Features

• 9 tools for Claude: list conversations, read messages, search, send, unread summary, action items
• E2E encrypted: Messages encrypted with sealed boxes (X25519 + XSalsa20-Poly1305)
• Your data, your DB: Messages stored in your own Neon database
• Media support: Images, audio (with Whisper transcription), PDFs
• Coexistence mode: Works with WhatsApp Business app alongside the API
• Action items: Create follow-up tasks from messages

Quick Start

1. Create your MCP account

Go to vidaai.co/mcp, log in, and connect your WhatsApp Business number. Save your API key.

2. Run setup

npx @vidaai/whatsapp-mcp setup

The setup wizard will:

• Validate your API key
• Connect to your Neon database (create one free at neon.tech)
• Generate your encryption keypair
• Activate WhatsApp webhooks

3. Add to Claude

Add this to ~/.claude/.mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@vidaai/whatsapp-mcp"],
      "env": {
        "VIDA_API_KEY": "sk_your_key_here",
        "NEON_DATABASE_URL": "postgresql://user:pass@ep-xxx.neon.tech/dbname",
        "VIDA_KEY_PATH": "~/.vida/private.key"
      }
    }
  }
}

4. Use it

You: "show me my WhatsApp messages from today"
You: "what did Maria send me?"
You: "reply to Juan: confirmed for tomorrow at 3"
You: "create an action item to follow up with Carlos about the contract"
You: "show me my pending action items"

Tools

Tool	Description
whatsapp_sync	Pull new messages from relay
whatsapp_list_conversations	List recent conversations with unread counts
whatsapp_read_messages	Read messages by contact name or conversation
whatsapp_search	Search messages by keyword, contact, date range
whatsapp_send_message	Send a message to a contact
whatsapp_unread_summary	Summary of all unread messages
whatsapp_create_action_item	Create a follow-up task
whatsapp_list_action_items	List tasks (pending/done)
whatsapp_complete_action_item	Mark a task as done

Privacy & Security

• Private key stays on your machine (~/.vida/private.key). Never sent anywhere.
• Messages are encrypted with sealed boxes before leaving WhatsApp's servers. Our relay stores only encrypted blobs.
• Your database is your own Neon instance. We don't have the connection string.
• API key is SHA-256 hashed on our server. The plaintext is shown once during registration.
• Audio transcription happens on our relay (Whisper) and is encrypted before storage. The audio is not persisted.

What we can see

Data	Our relay	Your MCP (local)
Message content	No (encrypted blob)	Yes
Sender phone	Yes (for routing)	Yes
Timestamp	Yes	Yes
Private key	Never	Yes
Your Neon URL	Never	Yes

What about outbound messages?

When you send a message through Claude, the plaintext briefly passes through our relay (WhatsApp requires it). It is not logged or stored in plaintext — after sending, we encrypt a copy for your sync history.

Coexistence Mode

If your WhatsApp number uses coexistence (both the app and API), be aware:

• Incoming messages: All visible (100%)
• Messages you send from your phone: Not visible to the MCP
• Messages you send through Claude: Visible

For full coverage, migrate your number fully to the WhatsApp Business API.

Environment Variables

Variable	Required	Description
VIDA_API_KEY	Yes	API key from vidaai.co/mcp
NEON_DATABASE_URL	Yes	Your Neon PostgreSQL connection string
VIDA_KEY_PATH	No	Path to private key (default: ~/.vida/private.key)

Development

git clone https://github.com/juancvergara1/whatsapp-mcp.git
cd whatsapp-mcp
npm install
npm run build
npm run check    # type check without build

License

MIT

Built by

VIDA AI — AI-powered WhatsApp automation for businesses.