WhatsApp MCP for macOS - Read messages from local DB, send via WhatsApp Web.
Check it out on https://mcp.paperknife.app/
A Model Context Protocol server that connects Claude to your WhatsApp. Ask Claude to catch you up on unread chats, search your message history, or send a reply.
Reading works in about a minute with no QR scan and no Node.js. Sending is optional and needs one extra step.
Search contacts by name or phone number. Read chat history with date filtering. List recent conversations with unread counts. Summarize everything you haven't read yet. Send replies and receive incoming messages once the bridge is connected.
You don't need to install Python. uvx fetches a suitable version on its own.
Install uv if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh
That's the whole install. uvx downloads the server on first launch, so there's no virtualenv to create and no pip install step. Go to the next section to point Claude at it.
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
uv venv && uv pip install -e .
Open config file:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
If it doesn't exist, create it.
Find the full path to uvx:
which uvx
Add the WhatsApp MCP server, pasting that path as the command:
{
"mcpServers": {
"whatsapp": {
"command": "/Users/YOU/.local/bin/uvx",
"args": ["whatsapp-mcp-macos"]
}
}
}
Use the absolute path, not bare uvx. Claude Desktop starts with a minimal PATH that doesn't include ~/.local/bin, so a bare command name is the most common reason the server never appears.
Restart Claude Desktop with Cmd+Q, then reopen. Closing the window is not enough.
Click the MCP tools icon in the chat input and check that "whatsapp" is listed.
Start chatting:
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"whatsapp": {
"command": "/Users/YOU/.local/bin/uvx",
"args": ["whatsapp-mcp-macos"]
}
}
}
Restart Cursor and use WhatsApp tools in the AI chat.
Just ask Claude:
Start the WhatsApp bridge:
cd bridge && npm install && npm start
Ask Claude to check connection:
If it shows a QR code, open the data URL in a browser and scan with your phone
Once connected, you can send:
| Tool | Description | Requires Bridge |
|---|---|---|
whatsapp_status | Check connection, get QR if needed | No |
whatsapp_search_contacts | Search contacts by name/phone | No |
whatsapp_list_chats | List recent conversations | No |
whatsapp_get_messages | Get messages from a chat | No |
whatsapp_search_messages | Search across all chats | No |
whatsapp_unread | Get unread message summary | No |
whatsapp_send | Send a message | Yes |
whatsapp_incoming | Get real-time incoming messages | Yes |
Claude ──MCP──▶ WhatsApp MCP Server
│
├──▶ Local SQLite DBs (read messages)
│ ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/
│
└──▶ WhatsApp Bridge (:3010) ──▶ WhatsApp Web
(for sending)
Read operations query the local WhatsApp database directly, so they work offline and need no bridge.
Send operations go through the bridge, which connects to WhatsApp Web using Baileys.
# Clone
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
# Install in dev mode
pip install -e ".[dev]"
# Run server
python -m whatsapp_mcp
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx whatsapp-mcp-macosMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-kalki-kgp-whatsapp-macos": {
"command": "uvx",
"args": [
"whatsapp-mcp-macos"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencewhatsapp-mcp-macospypiio.github.kalki-kgp/whatsapp-macos works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.