Whatsapp Mcp

WhatsApp MCP

MCP server for WhatsApp that connects to your personal WhatsApp account via the WhatsApp Web multi-device API (using the whatsmeow library). Single Go binary — no Python or separate bridge process needed. All messages are stored locally in SQLite and only sent to the LLM when accessed through tools.

Installation

Option A — Install script (macOS / Linux, no Go required)

curl -fsSL https://raw.githubusercontent.com/ihiteshgupta/whatsapp-mcp/main/install.sh | sh

Installs the whatsapp-mcp binary to /usr/local/bin.

Option B — Homebrew (macOS / Linux)

brew install ihiteshgupta/tap/whatsapp-mcp

> Requires the Homebrew tap to be set up. See ihiteshgupta/homebrew-tap.

Option C — go install (Go users)

go install github.com/ihiteshgupta/whatsapp-mcp/whatsapp-bridge-v2/cmd/whatsapp-mcp@latest

Option D — Build from source

git clone https://github.com/ihiteshgupta/whatsapp-mcp.git
cd whatsapp-mcp/whatsapp-bridge-v2
go build -o whatsapp-mcp ./cmd/whatsapp-mcp

> Windows: CGO is required for SQLite. Install MSYS2, add ucrt64\bin to PATH, then run go env -w CGO_ENABLED=1 before building.

---

Configure your MCP client

Claude Desktop / Claude Code

Add to your Claude config:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code: ~/.claude.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "/usr/local/bin/whatsapp-mcp",
      "args": []
    }
  }
}

> Replace /usr/local/bin/whatsapp-mcp with the actual path if you built from source (e.g. /path/to/whatsapp-mcp/whatsapp-bridge-v2/whatsapp-mcp).

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/usr/local/bin/whatsapp-mcp",
      "args": []
    }
  }
}

3. Authenticate

1. Start your MCP client (Claude Desktop, Claude Code, or Cursor)
2. A QR code will appear in the terminal and be saved to ~/.whatsapp-mcp/qrcode.png
3. Scan with WhatsApp on your phone (Settings → Linked Devices → Link a Device)
4. Wait for history sync to complete
5. Session persists in ~/.whatsapp-mcp/whatsapp.db — re-authentication needed every ~20 days

Data Storage

All data is stored locally in ~/.whatsapp-mcp/ (no config file needed):

• ~/.whatsapp-mcp/whatsapp.db — WhatsApp session (whatsmeow)
• ~/.whatsapp-mcp/messages.db — Messages, chats, contacts, groups
• ~/.whatsapp-mcp/qrcode.png — QR code image (created on first launch)

MCP Tools (55 total)

Messaging (8)

| Tool | Description | | --- | --- | | send_message | Send text message | | reply_to_message | Reply to a specific message | | forward_message | Forward a message | | edit_message | Edit a sent message | | delete_message | Delete a message | | react_to_message | Add emoji reaction | | star_message | Star a message | | unstar_message | Unstar a message |

Chats (11)

| Tool | Description | | --- | --- | | list_chats | List all chats | | get_chat | Get chat details | | list_messages | Get messages from a chat | | archive_chat | Archive a chat | | unarchive_chat | Unarchive a chat | | pin_chat | Pin a chat | | unpin_chat | Unpin a chat | | mute_chat | Mute chat notifications | | unmute_chat | Unmute a chat | | mark_chat_read | Mark chat as read | | delete_chat | Delete a chat |

Contacts (6)

| Tool | Description | | --- | --- | | search_contacts | Search contacts | | get_contact | Get contact details | | block_contact | Block a contact | | unblock_contact | Unblock a contact | | get_blocked_contacts | List blocked contacts | | check_phone_registered | Check if a phone number is registered |

Groups (13)

| Tool | Description | | --- | --- | | create_group | Create a new group | | get_group_info | Get group info | | leave_group | Leave a group | | add_group_members | Add members | | remove_group_members | Remove members | | promote_admin | Promote to admin | | demote_admin | Demote from admin | | set_group_name | Change group name | | set_group_topic | Change group topic | | set_group_photo | Change group photo | | get_invite_link | Get invite link | | revoke_invite_link | Revoke invite link | | join_via_invite | Join via invite link |

Media (7)

| Tool | Description | | --- | --- | | send_image | Send an image | | send_video | Send a video | | send_audio | Send audio/voice message | | send_document | Send a document | | send_location | Send a location | | send_contact_card | Send a contact card | | download_media | Download media from a message |

Presence (5)

| Tool | Description | | --- | --- | | subscribe_presence | Subscribe to presence updates | | send_typing | Send typing indicator | | send_recording | Send recording indicator | | set_online | Set presence online | | set_offline | Set presence offline |

Status (4)

| Tool | Description | | --- | --- | | post_text_status | Post text status | | post_image_status | Post image status | | get_status_updates | Get status updates | | delete_status | Delete status |

Bridge (2)

| Tool | Description | | --- | --- | | get_bridge_status | Get health status | | get_connection_history | Get connection history |

Troubleshooting

• QR Code not appearing: Check stderr output, or open ~/.whatsapp-mcp/qrcode.png
• Session expired: Delete ~/.whatsapp-mcp/whatsapp.db and restart to re-authenticate
• Out of sync: Delete both ~/.whatsapp-mcp/*.db files and restart
• Windows CGO error (Binary was compiled with 'CGO_ENABLED=0'): Install MSYS2, add ucrt64\bin to PATH, run go env -w CGO_ENABLED=1
• Device limit reached: Remove a device in WhatsApp → Settings → Linked Devices

Security Note

As with all MCP servers, be aware of prompt injection risks. This server can read your WhatsApp messages and send messages on your behalf — only connect trusted AI clients.

Development

cd whatsapp-bridge-v2
go test ./...
go build ./...

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ihiteshgupta
• Source: ihiteshgupta/whatsapp-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.