Skip to main content
Glama
WhatsApp MCP Server

WhatsApp MCP Server

by msaelices

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 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:

"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.

Available Tools

5 tools
create_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

    B3.2/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A 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.
      7
      76
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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