WhatsApp MCP Server
Provides tools to automate WhatsApp Web, enabling capabilities such as sending messages, retrieving message history, listing recent chats, and managing authentication status.
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 ServerSend 'I'll be there in 5 minutes' to John Appleseed"
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.
WhatsApp MCP Server
A local Python MCP server that automates WhatsApp Web through Playwright and exposes a small set of WhatsApp tools over stdio.
What this project does
Runs as an MCP server over stdio.
Uses Python instead of Node.
Uses Playwright with Chromium.
Persists the WhatsApp Web session under
./data/profile.
Related MCP server: MCP Playwright Server
Current tools
get_auth_statuswait_until_readylist_recent_chatssend_messageget_recent_messagesshutdown_browser
send_message and get_recent_messages accept either phone_number or chat_name. chat_name works by searching the existing WhatsApp sidebar/chat list.
For larger get_recent_messages requests, the server attempts to scroll upward and load older visible history before extracting messages.
Important limitations
This project automates WhatsApp Web, not the official WhatsApp Business API.
WhatsApp Web markup changes regularly, so selectors may need maintenance.
You should use a dedicated account and review WhatsApp's terms before production use.
The repository is initialized as a Git repository on the
mainbranch.
Recommended local setup
Copy the environment file:
cp .env.example .envCreate a virtual environment:
python3 -m venv .venv
source .venv/bin/activateInstall dependencies:
pip install -r requirements.txt
python3 -m playwright install chromiumFor local login, set
WHATSAPP_HEADLESS=falsein.env.Start the server locally:
PYTHONPATH=src python3 -m whatsapp_mcp.mainFrom your MCP client, call
get_auth_status.If a browser window opens, scan the QR code directly in that window.
Call
wait_until_ready.
Example MCP client configuration
For Claude Desktop or another MCP client, local Python execution is the recommended configuration.
{
"mcpServers": {
"whatsapp": {
"command": "/absolute/path/to/project/.venv/bin/python3",
"args": [
"-m",
"whatsapp_mcp.main"
],
"cwd": "/absolute/path/to/project",
"env": {
"PYTHONPATH": "/absolute/path/to/project/src",
"WHATSAPP_HEADLESS": "false",
"WHATSAPP_PROFILE_DIR": "/absolute/path/to/project/data/profile"
}
}
}
}Tool examples
get_auth_status
{
"name": "get_auth_status",
"arguments": {}
}send_message
{
"name": "send_message",
"arguments": {
"chat_name": "John Appleseed",
"text": "Hello from the WhatsApp MCP server"
}
}get_recent_messages
{
"name": "get_recent_messages",
"arguments": {
"chat_name": "John Appleseed",
"count": 10
}
}Project structure
.
├── docs/
├── src/whatsapp_mcp/
├── .env.example
└── pyproject.tomlDocumentation
Available Tools
6 toolsget_auth_statusB
Open WhatsApp Web if needed and report whether login is complete.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool may open WhatsApp Web and reports login status, but lacks details on behavioral traits such as side effects (e.g., browser automation, potential delays), error handling, or what 'report' entails. For a tool with no annotations, this is insufficient to fully inform an agent.
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?
The description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words. It is front-loaded with the core action and condition, making it easy to parse. Every part of the sentence earns its place by specifying the tool's behavior.
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?
Given the tool has no parameters, no annotations, and no output schema, the description provides basic context but lacks completeness. It doesn't explain what the output looks like (e.g., boolean status, detailed report) or potential errors. For a tool that interacts with external systems like WhatsApp Web, more detail on behavior and results would be beneficial.
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?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add parameter semantics, but that's acceptable here. A baseline of 4 is appropriate since the schema fully covers the absence of parameters, and the description doesn't need to compensate.
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?
The description clearly states the tool's purpose: 'Open WhatsApp Web if needed and report whether login is complete.' It specifies the action (open WhatsApp Web conditionally and report login status) and the resource (WhatsApp Web). However, it doesn't explicitly differentiate from sibling tools like 'wait_until_ready' which might also involve readiness checks, so it doesn't reach the highest score.
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?
The description implies usage context: use this tool to check login status, possibly before other operations. It suggests a conditional action ('if needed'), but doesn't provide explicit guidance on when to use it versus alternatives like 'wait_until_ready' or prerequisites for other tools like 'send_message'. The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_recent_messagesC
Read recent messages from a chat identified by either a phone number or a chat name.
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number | No | ||
| chat_name | No | ||
| limit | No | ||
| count | No | Alias for limit. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral context. It states 'Read' (implying read-only) but doesn't disclose rate limits, pagination, error conditions, or what 'recent' means temporally. No contradictions exist, but critical behavioral traits are missing.
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?
The description is a single, efficient sentence that front-loads the core purpose. However, it could be more structured by separating identification methods from the action, and it lacks necessary details that would justify additional sentences.
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?
Given no annotations, low schema coverage, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or behavioral constraints, making it inadequate for a tool with 4 parameters and read operations in a chat context.
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?
Schema description coverage is low (25%), with only 'count' having a description ('Alias for limit'). The description adds that phone_number or chat_name identify the chat, but doesn't explain format, exclusivity, or default behavior. It fails to compensate for the coverage gap, leaving most parameters semantically unclear.
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?
The description clearly states the action ('Read recent messages') and resource ('from a chat'), specifying identification by phone number or chat name. It distinguishes from siblings like 'send_message' (write vs read) and 'list_recent_chats' (messages vs chats), but doesn't explicitly differentiate from other read operations if they existed.
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?
No guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., authentication status from 'get_auth_status'), when to prefer phone_number vs chat_name, or how it relates to 'list_recent_chats' for discovering chats first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_recent_chatsC
List the most recent chats visible in WhatsApp Web.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it implies a read-only operation ('List'), it doesn't specify whether this requires authentication, what happens if WhatsApp Web isn't loaded, whether there are rate limits, or what format the output takes. The description provides minimal behavioral context beyond the basic action.
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?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a simple tool and gets straight to the point with zero waste.
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?
For a tool with no annotations, no output schema, and incomplete parameter documentation, the description is insufficient. It doesn't explain what 'recent' means, how results are ordered, what data is returned, or any error conditions. Given the complexity of interacting with WhatsApp Web, more context is needed for an agent to use this effectively.
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?
The schema has 0% description coverage, so the description must compensate. However, the description mentions no parameters at all, while the schema shows one optional 'limit' parameter. The description doesn't add any parameter semantics beyond what's already in the schema structure. Baseline 3 is appropriate since the schema provides the parameter definition.
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?
The description clearly states the action ('List') and resource ('most recent chats visible in WhatsApp Web'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling 'get_recent_messages', which could be confusing for an agent trying to choose between them.
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?
The description provides no guidance on when to use this tool versus alternatives like 'get_recent_messages' or 'get_auth_status'. There's no mention of prerequisites (like needing authentication), nor any context about what 'recent' means or how this differs from other chat-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_messageC
Send a WhatsApp message using either a phone number or an existing chat name.
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number | No | Recipient phone number in international or local format. | |
| chat_name | No | Visible WhatsApp chat name to open from the sidebar search. | |
| text | Yes | Message body to send. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action is 'send' (implying a write operation) but doesn't cover critical aspects like authentication requirements, rate limits, error conditions, or what happens if both phone_number and chat_name are provided. This leaves significant gaps for agent decision-making.
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?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a straightforward messaging tool and front-loads the essential information.
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?
For a write operation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, return values, error handling, or important behavioral constraints. The agent lacks critical information needed to use this tool effectively in context.
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?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value by mentioning the two recipient options (phone number or chat name) but doesn't provide additional syntax, format details, or usage context beyond what's in the schema descriptions.
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?
The description clearly states the action ('Send a WhatsApp message') and resource ('WhatsApp message'), specifying it can use either a phone number or chat name. However, it doesn't differentiate from sibling tools like 'get_recent_messages' or 'list_recent_chats' beyond the basic verb difference.
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?
The description mentions the two recipient options (phone number or chat name) but provides no guidance on when to choose one over the other, prerequisites for sending messages, or when to use this versus other messaging-related tools. No explicit alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shutdown_browserA
Close the browser context and stop the WhatsApp automation session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the behavioral outcome (closing browser and stopping automation), which is appropriate for a destructive operation. However, it doesn't mention whether this is reversible, what happens to unsaved data, or authentication implications, leaving some behavioral gaps.
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?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and consequence, making it immediately clear what the tool does without unnecessary elaboration.
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?
For a destructive operation with no annotations and no output schema, the description provides the essential purpose but lacks details about side effects, confirmation requirements, or what happens after shutdown. Given the complexity of terminating an automation session, more context about consequences would be helpful.
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?
With 0 parameters and 100% schema coverage, the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and doesn't need to compensate for any schema gaps.
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?
The description clearly states the specific action ('Close the browser context and stop the WhatsApp automation session'), which includes both the immediate effect (closing browser) and broader consequence (stopping automation). It distinguishes from sibling tools like 'get_auth_status' or 'send_message' by being the only termination operation.
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?
The description implies usage context (when ending an automation session), but doesn't explicitly state when to use this vs alternatives like 'wait_until_ready' or prerequisites. It's clear this should be used to terminate the session, but lacks explicit exclusions or comparison to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
wait_until_readyB
Wait until WhatsApp Web is fully authenticated and ready for use.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout_seconds | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions waiting for authentication and readiness, which implies this is a blocking operation, but it doesn't detail what 'fully authenticated and ready' entails (e.g., UI loaded, contacts synced), potential timeouts, error handling, or side effects. This leaves significant gaps in understanding the tool's behavior.
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?
The description is a single, clear sentence with zero wasted words—it directly states the tool's purpose without redundancy. It's appropriately sized and front-loaded, making it easy to grasp immediately.
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?
Given the tool's complexity (a blocking wait operation with no annotations, no output schema, and minimal parameter documentation), the description is incomplete. It doesn't explain what 'ready for use' means, what happens on timeout or failure, or what the agent should expect after invocation, leaving key contextual gaps for effective use.
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?
The input schema has one parameter ('timeout_seconds') with 0% description coverage, so the schema provides no semantic context. The description doesn't mention parameters at all, but since there's only one parameter and its purpose (timeout) is inferable from the name and schema constraints, the lack of explicit parameter info is less critical. However, it doesn't add meaning beyond what's minimally deducible.
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?
The description clearly states the action ('Wait until') and the target state ('WhatsApp Web is fully authenticated and ready for use'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_auth_status' (which checks status rather than waits), leaving room for slight ambiguity.
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?
The description implies usage when WhatsApp Web needs to be authenticated and ready, but it doesn't provide explicit guidance on when to use this versus alternatives like 'get_auth_status' (for checking status without waiting) or prerequisites (e.g., after launching the browser). It offers some context but lacks clear exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool has a clearly distinct purpose with no overlap: authentication status, message retrieval, chat listing, message sending, session shutdown, and readiness waiting. The descriptions make it unambiguous which tool to use for each task.
All tools follow a consistent verb_noun pattern (e.g., get_auth_status, send_message, shutdown_browser) with snake_case throughout. The naming is predictable and readable across all six tools.
Six tools is well-scoped for a WhatsApp automation server, covering core operations like authentication, messaging, chat management, and session control without being too sparse or bloated. Each tool earns its place in the workflow.
The toolset covers essential WhatsApp Web operations (authentication, messaging, chat listing) and session lifecycle (shutdown, readiness). Minor gaps might include advanced features like media handling or group management, but core workflows are well-supported.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
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…
MCP server for Sendbird — chat users, channels, members, and messages from your AI client.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseCqualityFmaintenanceA comprehensive MCP server that provides powerful web automation tools using Playwright, enabling web scraping, testing, and browser interaction through natural language commands.43815MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI-powered browser automation, web scraping, and testing using Playwright across Chromium, Firefox, and WebKit. It allows users to perform actions like navigation, clicking, typing, and taking screenshots through natural language interfaces.15MIT
- AlicenseBqualityCmaintenanceAn MCP server that enables interaction with WhatsApp using the Baileys library and Streamable HTTP transport. It supports managing contacts, chats, and messages, while providing a web admin UI for QR code authentication and media handling.285MIT
- AlicenseBqualityDmaintenanceAn MCP server that enables AI to control WhatsApp Web via Puppeteer Stealth for reading and sending messages. It features human-like interaction patterns and anti-ban protections to securely manage chats and communications through natural language.347MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ekaksher/whatsapp-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server