Connects to a personal WhatsApp account to search messages, access contacts, list recent chats, retrieve message history, and send messages to individuals or groups.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WhatsApp MCP Server search for messages from mom about dinner plans"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Model Context Protocol (MCP) server for WhatsApp, built with TypeScript and using the @whiskeysockets/baileys library.
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 your personal WhatsApp account using the WhatsApp Web multi-device API. All your messages and authentication details are stored locally in 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"
}Tool Result:
[
{
"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"
}Tool Result:
Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).Related MCP server: WAHA MCP
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 via Smithery:
npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claudeNode.js: Version 23.10.0 or higher (as specified in package.json). You can check your version with node -v. (Has initial typescript and sqlite builtin support)
npm (or yarn/pnpm): Usually comes with Node.js.
AI Client: Anthropic Claude Desktop app, Cursor, Cline or Roo Code (or another MCP-compatible client).
Clone this repository:
git clone <your-repo-url> whatsapp-mcp-ts
cd whatsapp-mcp-tsInstall dependencies:
npm install
# or yarn install / pnpm installRun the server for the first time:
Use node to run the main script directly.
node src/main.tsThe first time you run it, it will likely generate a QR code link using quickchart.io and attempt to open it in your default browser.
Scan this QR code using your WhatsApp mobile app (Settings > Linked Devices > Link a Device).
Authentication credentials will be saved locally in the auth_info/ directory (this is ignored by git).
Messages will start syncing and be stored in ./data/whatsapp.db. This might take some time depending on your history size. Check the wa-logs.txt and console output for progress.
Keep this terminal window running. After syncing you can close.
You need to tell your AI client how to start this MCP server.
Prepare the configuration JSON:
Copy the following JSON structure. You'll need to replace {{PATH_TO_REPO}} with the absolute path to the directory where you cloned this repository.
{
"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 the whatsapp-mcp-ts directory in your terminal and run pwd. Use this output for {{PATH_TO_REPO}}.
Save the configuration file:
For Claude Desktop: Save the JSON as claude_desktop_config.json in 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)
For Cursor: Save the JSON as mcp.json in its configuration directory:
~/.cursor/mcp.json
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 via node src/main.ts or 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/baileys to 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) using node:sqlite.
Runs an MCP server using @modelcontextprotocol/sdk that 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.
Uses pino for logging activity (wa-logs.txt for WhatsApp events, mcp-logs.txt for 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.db SQLite file.
Local Data: Both auth_info/ and data/ are included in .gitignore to 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 the quickchart.io URL and open it manually.
Ensure you scan the QR code promptly with your phone's WhatsApp app.
Authentication Failures / Logged Out:
If the connection closes with a DisconnectReason.loggedOut error, 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.
Message Sync Issues:
Initial sync can take time. Check wa-logs.txt for activity.
If messages seem out of sync or missing, you might need a full reset. Stop the server, delete both ./auth_info/ and ./data/ directories, then restart the server to re-authenticate and resync history.
MCP Connection Problems (Claude/Cursor):
Double-check the command and args (especially the {{PATH_TO_REPO}}) in your claude_desktop_config.json or mcp.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.
Errors Sending Messages:
Ensure the recipient JID is correct (e.g., number@s.whatsapp.net for users, groupid@g.us for groups).
Check wa-logs.txt for specific errors from Baileys.
General Issues: Check both wa-logs.txt and mcp-logs.txt for detailed error messages.
For further MCP integration issues, refer to the official MCP documentation.
https://github.com/lharries/whatsapp-mcp Do the same as this codebase but uses go and python.
This project is licensed under the ISC License (see package.json).
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | The JID of the chat to retrieve | |
| include_last_message | No | Include last message details (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The ID of the target message to get context around | |
| before | No | Number of messages before (default 5) | |
| after | No | Number of messages after (default 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max chats per page (default 20) | |
| page | No | Page number (0-indexed, default 0) | |
| sort_by | No | Sort order: 'last_active' (default) or 'name' | last_active |
| query | No | Optional filter by chat name or JID | |
| include_last_message | No | Include last message details (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | The JID of the chat (e.g., '123456@s.whatsapp.net' or 'group@g.us') | |
| limit | No | Max messages per page (default 20) | |
| page | No | Page number (0-indexed, default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term for contact name or phone number part of JID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The text content to search for within messages | |
| chat_jid | No | Optional: The JID of a specific chat to search within (e.g., '123...net' or 'group@g.us'). If omitted, searches all chats. | |
| limit | No | Max messages per page (default 10) | |
| page | No | Page number (0-indexed, default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| recipient | Yes | Recipient JID (user or group, e.g., '12345@s.whatsapp.net' or 'group123@g.us') | |
| message | Yes | The text message to send |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools are mostly distinct in purpose, with clear separation between chat operations (get_chat, list_chats), message operations (list_messages, search_messages, send_message), and contact operations (search_contacts). However, get_message_context and get_chat could potentially overlap in functionality if both retrieve chat data, creating minor ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case throughout (e.g., get_chat, list_messages, search_contacts). There are no deviations in naming conventions, making the set predictable and readable.
With 7 tools, this server is well-scoped for a WhatsApp integration, covering core functionalities like retrieving chats, messages, contacts, and sending messages. The count is appropriate, neither too sparse nor bloated, allowing comprehensive interaction without overwhelming complexity.
The toolset covers basic read and send operations for chats, messages, and contacts, but lacks update or delete capabilities (e.g., no update_message or delete_chat). This creates notable gaps in lifecycle coverage, though agents can still perform core messaging workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jlucaso1/whatsapp-mcp-ts'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
