WhatsApp

Whatsapp MCP Server implemented in Python

python

26

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "msaelices-whatsapp-mcp-server": {
      "command": "whatsapp-mcp",
      "args": [],
      "env": {
        "GREENAPI_API_TOKEN": "YOUR_GREENAPI_API_TOKEN",
        "GREENAPI_ID_INSTANCE": "YOUR_GREENAPI_ID_INSTANCE"
      }
    }
  }
}

The WhatsApp MCP Server provides a Model Context Protocol (MCP) interface that lets language models interact with WhatsApp functionality through the GreenAPI-enabled WhatsApp Cloud API. It is implemented in Python and leverages FastMCP for fast, WebSocket and HTTP access to a rich set of WhatsApp features, including messaging, group management, sessions, and chat history.

How to use

You run the WhatsApp MCP Server locally and connect your MCP-enabled client (such as Claude) to its MCP endpoints. The server exposes both WebSocket and HTTP interfaces so you can open sessions, send messages, manage groups, and retrieve chats and history through standard MCP tool calls. Start the server, connect to the MCP endpoints, and call the available tools to perform common WhatsApp actions in your conversations.

How to install

Prerequisites: Python 3.8+ and pip must be available on your system.

Steps to install and run the server locally:

# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git
cd whatsapp-mcp-server

# Install dependencies (editable install)
pip install -e .

# Set up environment variables
cp .env-template .env
# Edit the .env file with your GreenAPI credentials (GREENAPI_ID_INSTANCE and GREENAPI_API_TOKEN)

Configuration and security

Configure your GreenAPI credentials to enable WhatsApp interactions. The server relies on GREENAPI_ID_INSTANCE and GREENAPI_API_TOKEN to authenticate with WhatsApp via GreenAPI. Keep these values secure and do not commit them to public repositories.

Run-time environment variables shown in usage examples must be provided either in your shell or via a .env file prior to starting the server.

Troubleshooting

If you encounter connection issues, verify that your GreenAPI credentials are correct and that the server can reach the GreenAPI endpoints. Check that the port you choose is not blocked by a firewall and that the host is accessible from your client.

Notes

The server exposes a set of MCP tools for common actions like opening sessions, sending messages, listing chats, creating groups, and listing group participants. Use these tools through your MCP client to automate WhatsApp workflows.

Available tools

open_session

Open a new WhatsApp session to begin interactions with the WhatsApp API via MCP.

send_message

Send a text message to a specified WhatsApp chat or contact.

get_chats

Retrieve a list of chats and conversation histories available to the connected WhatsApp account.

create_group

Create a new WhatsApp group with specified participants.

get_group_participants

Fetch the list of participants in a WhatsApp group.