WhatsApp (TypeScript/Baileys)

Connects a personal WhatsApp account to an AI agent using the WhatsApp Web multi-device API.

WhatsApp MCP Server (TypeScript/Baileys)

This is a Model Context Protocol (MCP) server for WhatsApp, built with TypeScript and using the@whiskeysockets/baileyslibrary.

It allows you to connect your personal WhatsApp account to an AI agent (like Anthropic Claude via its desktop app or Cursor) enabling it to:

- Search your personal WhatsApp messages.
- Search your contacts (individuals, not groups).
- List your recent chats.
- Retrieve message history for specific chats.
- Send messages to individuals or groups.

It connects directly to yourpersonal WhatsApp accountusing the WhatsApp Web multi-device API. All your messages and authentication details are storedlocallyin a SQLite database (./data/) and authentication cache (./auth_info/). Data is only sent to the connected AI agent when it explicitly uses the provided MCP tools (which you control via the agent's interface).

(Optional: Consider adding a screenshot or GIF similar to the reference example here)

User:Send a whatsapp message to "Meu amor" in whatsapp saying "Te amo"

Assistant:Okay, I need to find the contact first.Using tool:whatsapp.search_contacts

{ "query": "Meu amor" }

[ { "jid": "5599xxxxxx@s.whatsapp.net", "name": "Meu Amor" } ]

Assistant:Found the contact. Now sending the message.Using tool:whatsapp.send_message

{ "recipient": "5599xxxxxx@s.whatsapp.net", "message": "Te amo" }

Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).

The server exposes the following tools to the connected AI agent:

- search_contacts: Search for contacts by name or phone number part (JID).
- list_messages: Retrieve message history for a specific chat, with pagination.
- list_chats: List your chats, sortable by activity or name, filterable, paginated, optionally includes last message details.
- get_chat: Get detailed information about a specific chat.
- get_message_context: Retrieve messages sent immediately before and after a specific message ID for context.
- send_message: Send a text message to a specified recipient JID (user or group).

To install WhatsApp MCP Server for Claude Desktop automatically viaSmithery:

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

git clone <your-repo-url> whatsapp-mcp-ts cd whatsapp-mcp-ts

npm install # or yarn install / pnpm install

{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "{{PATH_TO_REPO}}/src/main.ts" ], "timeout": 15, // Optional: Adjust startup timeout if needed "disabled": false } } }

- Get the absolute path:Navigate to thewhatsapp-mcp-tsdirectory in your terminal and runpwd. Use this output for{{PATH_TO_REPO}}.

- ForClaude Desktop:Save the JSON asclaude_desktop_config.jsonin its configuration directory:

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json(Likely path, verify if needed)
- Linux:~/.config/Claude/claude_desktop_config.json(Likely path, verify if needed)

Restart Claude Desktop / Cursor:Close and reopen your AI client. It should now detect the "whatsapp" MCP server and allow you to use its tools.

Once the server is running (either manually vianode src/main.tsor started by the AI client via the config file) and connected to your AI client, you can interact with your WhatsApp data through the agent's chat interface. Ask it to search contacts, list recent chats, read messages, or send messages.

This application is a single Node.js process that:
- Uses@whiskeysockets/baileysto connect to the WhatsApp Web API, handling authentication and real-time events.
- Stores WhatsApp chats and messages locally in a SQLite database (./data/whatsapp.db) usingnode:sqlite.
- Runs an MCP server using@modelcontextprotocol/sdkthat listens for requests from an AI client over standard input/output (stdio).
- Provides MCP tools that query the local SQLite database or use the Baileys socket to send messages.
- Usespinofor logging activity (wa-logs.txtfor WhatsApp events,mcp-logs.txtfor MCP server activity).

- Authentication:Your WhatsApp connection credentials are stored locally in the./auth_info/directory.
- Messages & Chats:Your message history and chat metadata are stored locally in the./data/whatsapp.dbSQLite file.
- Local Data:Bothauth_info/anddata/are included in.gitignoreto prevent accidental commits.Treat these directories as sensitive.
- LLM Interaction:Data is only sent to the connected Large Language Model (LLM) when the AI agent actively uses one of the provided MCP tools (e.g.,list_messages,send_message). The server itself does not proactively send your data anywhere else.

- Language:TypeScript
- Runtime:Node.js (>= v23.10.0)
- WhatsApp API:@whiskeysockets/baileys
- MCP SDK:@modelcontextprotocol/sdk
- Database:node:sqlite(Bundled SQLite)
- Logging:pino
- Schema Validation:zod(for MCP tool inputs)

- QR Code Issues:

- If the QR code link doesn't open automatically, check the console output for thequickchart.ioURL and open it manually.
- Ensure you scan the QR code promptly with your phone's WhatsApp app.

- If the connection closes with aDisconnectReason.loggedOuterror, you need to re-authenticate. Stop the server, delete the./auth_info/directory, and restart the server (node src/main.ts) to get a new QR code.

- Initial sync can take time. Checkwa-logs.txtfor activity.
- If messages seem out of sync or missing, you might need a full reset. Stop the server, deleteboth./auth_info/and./data/directories, then restart the server to re-authenticate and resync history.

- Double-check thecommandandargs(especially the{{PATH_TO_REPO}}) in yourclaude_desktop_config.jsonormcp.json. Ensure the path is absolute and correct.
- Verify Node.js are correctly installed and in your system's PATH.
- Check the AI client's logs for errors related to starting the MCP server.
- Check this server's logs (mcp-logs.txt) for MCP-related errors.

- Ensure the recipient JID is correct (e.g.,number@s.whatsapp.netfor users,groupid@g.usfor groups).
- Checkwa-logs.txtfor specific errors from Baileys.

For further MCP integration issues, refer to theofficial MCP documentation.

- https://github.com/lharries/whatsapp-mcpDo the same as this codebase but uses go and python.

An MCP server client for the Agent-to-Agent (A2A) protocol, enabling LLMs to interact with A2A agents.