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.

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 instance
GREENAPI_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 credentials

Usage

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 9000

For debugging:

whatsapp-mcp --debug

The 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 session
send_message: Send a message to a chat
get_chats: Get a list of chats
create_group: Create a new WhatsApp group
get_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/mcp
HTTP: 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
claude

Using with Claude

Once the WhatsApp MCP server is running, you can interact with it using Claude in your conversations:

Authenticating with WhatsApp

Login to WhatsApp

Sending a message

Send the "Hello" message to John Doe

Using 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-mcp
View 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.

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

A Python server that enables language models like Claude to interact with WhatsApp Business API through GreenAPI, supporting features like sending messages and managing groups.

Related MCP Servers

WhatsApp Web MCP
fyimail
-
security
A
license
-
quality
A bridge that connects WhatsApp Web to AI models using the Model Context Protocol, enabling Claude and other AI systems to interact with WhatsApp through a standardized interface.
Last updated -
19
4
TypeScript
MIT License
MCP Evolution API
aiteks-ltda
-
security
A
license
-
quality
A Model Context Protocol server that enables Claude to interact with WhatsApp through the Evolution API, allowing for message sending, contact management, group operations, and WhatsApp instance administration.
Last updated -
7
10
TypeScript
MIT License
WhatsApp Web MCP
pnizer
-
security
A
license
-
quality
A Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol, enabling automated messaging, contact management, and group chat functionality through AI-driven workflows.
Last updated -
19
18
TypeScript
MIT License
WhatsApp MCP Server
gfb-47
A
security
F
license
A
quality
A Node.js application that enables programmatic interaction with WhatsApp desktop on macOS, allowing users to send messages and check WhatsApp status through AppleScript automation without direct UI interaction.
Last updated -
3
2
TypeScript

View all related MCP servers

WhatsApp MCP Server