WhatsApp MCP Assistant

whatsapp-mcp-assistant — MCP server that exposes a real WhatsApp account to Cursor through safe, approval-gated tools and a local bridge.

This project exposes a real WhatsApp account to Cursor through an MCP server. Cursor is the agent interface; this repo only provides MCP tools and a local WhatsApp bridge.

V1 uses:

• Python FastMCP server for Cursor.
• Local Go whatsmeow HTTP bridge for WhatsApp Web login and messaging.
• Real per-user WhatsApp sessions stored locally under sessions/.
• No mock WhatsApp data.

Tools

• get_connection_status()
• get_login_qr()
• logout_whatsapp(confirm)
• get_recent_chats(limit=10, unread_only=false, include_groups=true)
• search_contact(query, include_groups=true, limit=5)
• get_messages_from_contact(chat_id, limit=20, include_outgoing=true)
• draft_reply(chat_id, instruction, recent_messages=[], tone="natural")
• send_whatsapp_message(chat_id, message, approved)

send_whatsapp_message rejects every request unless approved=true.

Setup

Install Python dependencies:

python -m pip install -r requirements.txt

Install Go, then install Go bridge dependencies:

cd go-whatsapp-bridge
go mod tidy

Start the WhatsApp bridge:

go run .

Start Cursor with this MCP server config shape:

{
  "mcpServers": {
    "whatsapp-assistant": {
      "command": "python",
      "args": complete path like ["/AI/MCP Server/server.py"]
    }
  }
}

QR Login Flow

1. Start the Go bridge.
2. Ask Cursor: Check WhatsApp connection.
3. If disconnected, ask Cursor: Get WhatsApp login QR.
4. Scan the returned QR string using WhatsApp > Linked Devices.
5. Ask Cursor to check connection again.

Every user must run the server locally and scan their own WhatsApp QR. Do not share sessions/, .env, QR codes, tokens, or connected server instances.

Demo Flow

Use a test WhatsApp number.

1. Send a WhatsApp message from another phone to the connected test account.
2. Ask Cursor: Show my recent WhatsApp chats.
3. Ask Cursor: What did Bilal message me today?
4. Ask Cursor: Draft a reply saying I will come at 6.
5. After reviewing the draft, say: Okay, send it.

Current Bridge Limitation

The local bridge records real messages it receives while the bridge is running and keeps them in sessions/message_cache.json. WhatsApp Web libraries do not reliably provide full historical chat export through this simple bridge, so test by sending messages after the bridge is connected.