WhatsApp MCP Server
This server provides a Model Context Protocol (MCP) interface to interact with WhatsApp Business API, enabling you to:
Open WhatsApp sessions
Send text messages to contacts (with optional reply functionality)
Retrieve chat lists with pagination options
Create WhatsApp groups with specified participants
Manage group participants
Enables messaging (send text messages) and group management (create groups, list members, add/remove participants) through the WhatsApp Business API via GreenAPI
Click on "Deploy 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 send a message to John Doe saying 'Meeting at 3 PM tomorrow'"
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 server that provides a Model Context Protocol (MCP) interface to interact with WhatsApp Business API using FastMCP.
Introduction
WhatsApp MCP Server is a Python implementation that enables language models like Claude to interact with WhatsApp functionality through GreenAPI. It leverages FastMCP for improved performance, better developer experience, and a cleaner implementation.
Related MCP server: YCloud WhatsApp API MCP Server
Features
Messaging: Send text messages to WhatsApp contacts
Group Management: Create groups, list members, add/remove participants
Session Handling: Manage WhatsApp API sessions
Chat History: Retrieve chat lists and message history
WhatsApp API Client
This project uses the whatsapp-api-client-python library to interact with WhatsApp. The client provides access to the WhatsApp Cloud API, which requires a GreenAPI account to use.
Environment Variables
This project uses environment variables for configuration:
GREENAPI_ID_INSTANCE: Your GreenAPI ID instanceGREENAPI_API_TOKEN: Your GreenAPI API token
You can either set these in your environment or use the provided .env file (see Installation instructions).
Installation
# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git
cd whatsapp-mcp-server
# Install dependencies
pip install -e .
# Set up environment variables
cp .env-template .env
# Edit the .env file with your GreenAPI credentialsUsage
Run the MCP server:
# Run the MCP server on default host (127.0.0.1) and port (8000)
whatsapp-mcp
# Specify host and port
whatsapp-mcp --host 0.0.0.0 --port 9000For debugging:
whatsapp-mcp --debugThe server communicates using the Model Context Protocol (MCP) and can be accessed via HTTP or WebSockets when running with FastMCP.
Available Tools
open_session: Open a new WhatsApp sessionsend_message: Send a message to a chatget_chats: Get a list of chatscreate_group: Create a new WhatsApp groupget_group_participants: Get the participants of a group
FastMCP API Reference
The WhatsApp MCP Server uses FastMCP to provide both WebSocket and HTTP endpoints:
WebSocket:
ws://localhost:8000/mcpHTTP:
http://localhost:8000/mcp
You can test the API directly using tools like curl:
# List available tools
curl -X POST http://localhost:8000/mcp/listTools
# Call a tool
curl -X POST http://localhost:8000/mcp/callTool \
-H "Content-Type: application/json" \
-d '{"name": "open_session", "arguments": {}}'How to add it to Claude Code
To add a WhatsApp server to Claude, use the claude mcp add command:
# Add the WhatsApp MCP server
$ claude mcp add whatsapp -- whatsapp-mcp
# List existing MCP servers - Validate that the server is running
claude mcp list
# Start claude code
claudeUsing with Claude
Once the WhatsApp MCP server is running, you can interact with it using Claude in your conversations:
Authenticating with WhatsApp
Login to WhatsAppSending a message
Send the "Hello" message to John DoeUsing with Claude Desktop
To use the WhatsApp MCP server with Claude Desktop, you need to add it to your claude_desktop_config.json file:
Using pip installation (recommended)
"mcpServers": {
"whatsapp": {
"command": "python",
"args": ["-m", "whatsapp_mcp"]
}
}Using the executable
"mcpServers": {
"whatsapp": {
"command": "whatsapp-mcp"
}
}Using Docker
"mcpServers": {
"whatsapp": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "GREENAPI_ID_INSTANCE=your_instance_id", "-e", "GREENAPI_API_TOKEN=your_api_token", "whatsapp-mcp-server"]
}
}Remember to set your GreenAPI credentials either as environment variables or in your .env file before starting Claude Desktop.
Command-line options
The WhatsApp MCP server accepts these command-line arguments:
--debug: Increase verbosity level for debugging--host: Host to bind the server to (default: 127.0.0.1)--port: Port to bind the server to (default: 8000)
Debugging
For debugging the MCP server:
Use MCP inspector:
npx @modelcontextprotocol/inspector whatsapp-mcpView logs in your Claude Desktop logs directory (typically
~/Library/Logs/Claude/on macOS)Access the FastMCP web interface at http://localhost:8000 for interactive API documentation
Development
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
flake8 src/
# Run type checking
mypy src/The project uses a modern pyproject.toml configuration which includes:
Core dependencies needed for running the application
Development dependencies available with
pip install -e ".[dev]"
License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
5 toolscreate_groupC
Create a new WhatsApp group.
Parameters:
- group_name: Name of the group to create
- participants: List of participant phone numbers
Inputs: group_name (required), participants (required).
get_chatsC
Get a list of chats.
Parameters:
- limit: Maximum number of chats to return (default: 50)
- offset: Offset for pagination (default: 0)
Inputs: limit, offset.
get_group_participantsB
Get the participants of a WhatsApp group.
Parameters:
- group_id: The WhatsApp ID of the group
Inputs: group_id (required).
open_sessionB
Open a new WhatsApp session.
Inputs: no named parameters.
send_messageC
Send a message to a chat.
Parameters:
- phone_number: The phone number of the recipient
- content: The content of the message to send
- reply_to: ID of the message to reply to (optional)
Inputs: content (required), phone_number (required), reply_to.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Most tools have distinct purposes: creating groups, listing chats, getting group participants, opening sessions, and sending messages. However, 'get_chats' could potentially overlap with group-related functionality since groups are a type of chat, but the descriptions clarify their focus areas.
The naming follows a consistent verb_noun pattern (e.g., create_group, get_chats, send_message) with clear, descriptive names. The only minor deviation is 'open_session', which uses a verb_adjective_noun structure but remains readable and fits the pattern conceptually.
With 5 tools, the count is reasonable for a WhatsApp server, covering core operations like messaging, group management, and session handling. It might benefit from additional tools for actions like deleting messages or managing contacts, but it's well-scoped for basic functionality.
The toolset covers key areas such as sending messages, creating groups, and retrieving chats/participants, but has notable gaps. For example, there are no tools for updating or deleting groups, managing contacts, or handling message reactions, which could limit agent workflows in a messaging domain.
Maintenance
Related MCP Connectors
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Hosted WhatsApp MCP for Claude and ChatGPT: read chats, find who awaits a reply.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server that connects your personal WhatsApp account to AI agents like Claude, enabling them to search messages, view contacts, retrieve chat history, and send messages via WhatsApp.776ISC
- AlicenseCqualityFmaintenanceA server that enables AI models like Claude to directly interact with YCloud WhatsApp API through natural language, automatically generating tools from the OpenAPI specification.1911MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables interaction with WhatsApp through local stdio or remote HTTP/SSE connections. It allows users to send messages, manage groups, and access chat history using natural language.3-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects Claude and other LLM clients to WhatsApp via the Baileys library. Enables sending and receiving messages, listing chats, downloading media, and more.MIT