Server facts
WhatsApp MCP Server
Project
- Author
- lharries
- Repository
- github.com/lharries/whatsapp-mcp
- License
- MIT
- Category
- Communication
Tech
- Runtime / language
- goGo and Python
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 6,633
- Last commit
- Data as of
Tags
- Contacts
- Local Storage
- Messaging
Overview
WhatsApp MCP Server gives an assistant access to a personal WhatsApp account through the web multidevice interface. It combines a Go bridge, which handles the WhatsApp connection and authentication, with a Python MCP server that exposes the assistant-facing tools. Message history is kept in a local SQLite database. The README explains that messages reach an LLM when the agent requests them through tools, rather than describing a continuous upload of the entire archive. Both components must remain running for the integration to work.
The toolset supports contact lookup, chat listings, filtered message retrieval, and the surrounding context of an individual message. Users can also locate a direct conversation or inspect the latest interaction with a contact. Sending covers individual recipients and groups, with separate tools for files and playable voice messages. Audio intended as a voice message needs the documented Opus format, or FFmpeg for automatic conversion. Media content is downloaded on demand because the database initially retains its metadata. Initial setup requires scanning a QR code using the mobile app, and sessions may eventually need authentication again. Windows users additionally need CGO and a C compiler for the SQLite bridge dependency. The README warns that combining private messages and agent tools creates a prompt-injection risk that could expose sensitive data.
Install & configure
Requirements
- Go
- Python 3.6+
- uv
- Claude Desktop or Cursor
- A personal WhatsApp account and mobile app
'{{PATH_TO_UV}}' --directory '{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server' run main.pyReplace the README path placeholders with your uv executable and cloned source location. First run go run main.go in whatsapp-bridge and authenticate by QR code. FFmpeg is optional for voice conversion; Windows needs CGO and a C compiler.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"whatsapp-mcp": {
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"whatsapp-mcp": {
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"whatsapp-mcp": {
"type": "stdio",
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"whatsapp-mcp": {
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"whatsapp-mcp": {
"type": "stdio",
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| search_contacts | Find WhatsApp contacts using a name or phone number. |
| list_messages | Retrieve messages using filters and optional contextual information. |
| list_chats | Enumerate chats along with their metadata. |
| get_chat | Inspect one chat's information. |
| get_direct_chat_by_contact | Locate a one-to-one conversation for a contact. |
| get_contact_chats | Find conversations in which a contact participates. |
| get_last_interaction | Retrieve the latest message exchanged with a contact. |
| get_message_context | Read messages surrounding a selected message. |
| send_message | Send text to a phone number or group JID. |
| send_file | Send a supported image, video, document, or raw audio file. |
| send_audio_message | Send playable voice audio using Opus input or FFmpeg conversion. |
| download_media | Fetch a message attachment and return its local path. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Find a past message and inspect its surrounding conversation.
- Locate contacts and their direct chats.
- Send text or documents to an individual or group.
- Download received media or send a playable voice message.
Strengths
- Keeps message history in a local SQLite database.
- Supports conversation context as well as contacts and chat metadata.
- Handles text, files, downloads, and voice messages.
Limitations
- Requires both the Go bridge and Python server to run.
- QR authentication can need renewal; initial history loading may take time.
- Private chat content can create prompt-injection and data-exposure risks.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
