M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
W

WhatsApp MCP

Community
Read, search, and send WhatsApp messages via Claude
How to install ↓ Compare GitHub source repository ↗
Category
Other #119 of 230
Stars
★ 248 Very popular
Transport
stdio (local process)
Runtime
Go 1.25+ · Python 3.11+
Credentials
No credential needed
License
Other / unspecified
Last commit
Tools
14
54FMRS · D

The server is feature-rich, supporting a variety of message operations and media handling. However, security risks and compliance issues with the unofficial API should be noted. It is suitable for personal or development use; for production, careful evaluation is required.

Strongest · Documentation 15/20 Weakest · Reliability 7/20

Reliability
7/20
Security and permissions
11/20
Maintenance
11/20
Documentation
15/20
Setup experience
10/20
Why each score
Reliability 7/20
The manifest and README tool lists are broadly consistent (13 tools), but the README documents send_reaction in detail while the manifest omits it, and the README's architecture diagram claims “14 total” — an internal contradiction. The README claims CI, pytest tests, Go lint, and Release Please, but none of this is verifiable from the supplied material, and README is untrusted evidence; per static calibration, reliability cannot exceed 12 without verifiable execution evidence. The Go-bridge plus Python-server architecture, QR pairing, and token handshake add many failure points, and the README itself lists extensive troubleshooting scenarios. Score: 7.
Security and permissions 11/20
Evidence shows deliberate controls: bearer-token auth on every bridge API call, loopback-only Host header checks, media-path confinement to WHATSAPP_MEDIA_ROOTS, loopback default for HTTP/SSE transports, owner-only token file permissions, no redirect-following in the webhook client, and no real tokens in install examples. However, the server's purpose is to give an LLM read access to private messages and the ability to send messages/files; the README's own Security Notice acknowledges prompt-injection-driven data exfiltration risk. No per-operation confirmation mechanism for send_message/send_file is described. No red-line trigger, but the inherent sensitivity of the data plane and the missing confirmation gate cap the score at 11.
Maintenance 11/20
The repository is not archived, has a concrete version (0.4.1), and the README cites Release Please, Dependabot, CI, a changelog, and named contributors — plausible maintenance activity. But the GitHub metadata reports License: NOASSERTION while the README claims MIT, and the supplied material contains no commit/release dates or issue responsiveness evidence, so sustained maintenance cannot be verified. The license discrepancy plus unverifiable governance claims keep the score at 11.
Documentation 15/20
The README is unusually thorough: prerequisites, quick start, Claude Desktop and Cursor config JSON, per-tool parameters with natural-language examples, a configuration table, transport modes, troubleshooting, a security notice, call-history schema, architecture diagrams, development commands, and disclosed limits (e.g., message/chat caps, phone-controlled history window). Deductions: send_reaction is documented but missing from the server manifest; the architecture diagram says 14 tools while the manifest lists 13; the LICENSE file and docs/RELEASING.md / CONTRIBUTING.md cannot be verified from the provided material. Score: 15.
Setup experience 10/20
The README gives clear step-by-step instructions, ready-to-paste client configs for Claude Desktop and Cursor, and an optional macOS launchd installer. But the stack is heavy: Go 1.25+, Python 3.11+, uv, phone QR pairing, and two separately running components (Go bridge + Python server). The manifest advertises a PyPI package, yet the quick start never uses it — it clones the repo and points uv at the local directory — and a PyPI-only install would lack the Go bridge. Windows additionally requires MSYS2 and CGO. Per static calibration, setup cannot exceed 15 without verifiable execution evidence; this is a manual, multi-component path, so the score is 10.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesUses the networkConnects to a database

Best for

  • Individual users who want to manage WhatsApp messages with an AI assistant while keeping local message records
  • Developers needing programmatic access to WhatsApp chat data

Not for

  • Environments with high security requirements for WhatsApp messages (prompt injection risks)
  • Large enterprise deployments requiring official WhatsApp API support (this server uses unofficial Web API)
  • Multi-user setups or those needing fine-grained access control (current implementation is single-user)

Required permissions

  • Read and send WhatsApp messages (via bridge)
  • Read and write message history in local SQLite database
  • Send and receive media files
  • Access local file system (for media file paths)
  • Listen on local REST API port (default 8080)

Risks and side effects

  • Prompt injection: malicious messages could trick the AI into performing unintended actions, leading to data exfiltration
  • Unofficial API: uses reverse-engineered WhatsApp Web API, potentially violating WhatsApp's terms of service
  • Sensitive data exposure: messages are stored locally, but the AI might send content to external services
  • No authentication: the MCP server itself has no authentication, and if exposed to network, it can be abused

Setup

Before you start

Runtime：Go 1.25+ · Python 3.11+

WHATSAPP_BRIDGE_TOKEN optionalsecret Bearer token for bridge REST calls; generated on first bridge start and stored in .bridge-token.
Other optional settings (10)
WHATSAPP_BRIDGE_PORT optional Port for the Go bridge REST API, default 8080.
WEBHOOK_URL optional Webhook endpoint for forwarded incoming messages, default http://localhost:8769/whatsapp/webhook.
FORWARD_SELF optional Whether to forward messages sent by yourself, default true.
WHATSAPP_DB_PATH optional Path to the local SQLite message database, default ../whatsapp-bridge/store/messages.db.
WHATSMEOW_DB_PATH optional Path to the whatsmeow session DB used for LID↔phone resolution, default ../whatsapp-bridge/store/whatsapp.db.
WHATSAPP_API_URL optional Go bridge REST API URL, default http://localhost:8080/api.
WHATSAPP_MEDIA_ROOTS optional Whitelist of directories allowed for outbound media files, default ~/.local/share/whatsapp-mcp/outbox.
WHATSAPP_MCP_TRANSPORT optional MCP transport to serve: stdio, http, or sse; default stdio.
WHATSAPP_MCP_HOST optional Bind address for http/sse transports, default 127.0.0.1.
WHATSAPP_MCP_PORT optional Port for the http/sse transports, default 8000.
  1. Clone the repository and navigate to the directory.
  2. Start the Go bridge: cd whatsapp-bridge && go run .. On first start, scan the QR code to authenticate.
  3. Add the MCP server configuration to Claude Desktop's config file (claude_desktop_config.json) or Cursor's config (~/.cursor/mcp.json) using the uv command with the whatsapp-mcp-server directory.
  4. Restart Claude Desktop or Cursor.
claude_desktop_config.json 
{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "whatsapp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add whatsapp -- uv --directory /path/to/whatsapp-mcp/whatsapp-mcp-server run main.py

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

Start the Go bridge (cd whatsapp-bridge && go run .), scan the QR code, then restart Claude Desktop — tools like search_contacts and list_messages should appear in the client's tool list; asking "List my chats" confirms the connection works.

Troubleshooting

  1. QR code not displaying: restart the bridge, check terminal QR code support
  2. Device limit reached: remove a linked device from WhatsApp Settings > Linked Devices
  3. No messages loading: initial sync may take several minutes; ensure bridge is running
  4. Bridge returns 401 Unauthorized: restart bridge to generate .bridge-token, then restart MCP server
  5. Bridge returns 403 Forbidden for Host: ensure WHATSAPP_API_URL uses 127.0.0.1 or localhost
  6. Media path rejected: move file to default outbox or configure WHATSAPP_MEDIA_ROOTS

Things to try

Once connected, you can ask your AI assistant things like:

  • Search contacts named John
  • Show me the last 100 messages from today
  • Send 'Hello!' to +1234567890
  • React to the last message in the family group chat with a thumbs up

Tools 14

search_contacts read-only
Search contacts by name or phone number
get_contact read-only
Resolve phone number to contact name
list_messages read-only
Get messages with filters, date ranges, and sorting
list_chats read-only
List all chats with metadata
get_chat read-only
Get specific chat metadata by JID
get_direct_chat_by_contact read-only
Find direct message chat with a contact
get_contact_chats read-only
List all chats involving a contact
get_last_interaction read-only
Get last message with a contact
Show 6 more tools
get_message_context read-only
Get messages around a specific message
send_message writes
Send text message to contact or group
send_reaction writes
Send (or remove) an emoji reaction to a message
send_file writes
Send media file (image, video, document)
send_audio_message writes
Send voice message (auto-converts to Opus)
download_media writes
Download media from a received message

Use cases

Let Claude send WhatsApp messages to contacts
Query chat history and retrieve specific conversations
Automatically download received media files
Integrate WhatsApp messages into AI workflows

Supported clients

Claude Desktop
Cursor

Listed from the project's documentation, not tested by this site.

Overview

This is a Model Context Protocol (MCP) server that connects Claude to WhatsApp, enabling message reading, searching, and sending. It consists of a Python MCP server and a Go bridge that interacts with WhatsApp via the WhatsApp Web API, storing messages locally in SQLite. The server provides tools for contact search, message listing, chat management, media send/download, and webhook forwarding of incoming messages.

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 659 · Tools 11 Compare with this →
Compare with other MCP servers

Source revision 895404542017 Data synced 2026-10-19 Read the FMRS scoring method