Servidor MCP de WhatsApp

Un servidor que proporciona una interfaz de Protocolo de contexto de modelo (MCP) para interactuar con la API de WhatsApp Business mediante FastMCP.

Introducción

El servidor MCP de WhatsApp es una implementación de Python que permite que modelos de lenguaje como Claude interactúen con las funciones de WhatsApp a través de GreenAPI . Aprovecha FastMCP para mejorar el rendimiento, la experiencia del desarrollador y una implementación más limpia.

Related MCP server: MCP Evolution API

Características

Mensajería : Envía mensajes de texto a contactos de WhatsApp
Gestión de grupos : crear grupos, enumerar miembros, agregar o eliminar participantes
Manejo de sesiones : Administrar sesiones de la API de WhatsApp
Historial de chat : recupera listas de chat e historial de mensajes

Cliente API de WhatsApp

Este proyecto utiliza la biblioteca whatsapp-api-client-python para interactuar con WhatsApp. El cliente proporciona acceso a la API de WhatsApp Cloud, que requiere una cuenta GreenAPI para su uso.

Variables de entorno

Este proyecto utiliza variables de entorno para la configuración:

GREENAPI_ID_INSTANCE : Su instancia de ID de GreenAPI
GREENAPI_API_TOKEN : Su token de API GreenAPI

Puede configurarlos en su entorno o utilizar el archivo .env proporcionado (consulte las instrucciones de instalación).

Instalación

# 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

Uso

Ejecute el servidor MCP:

# 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

Para depurar:

whatsapp-mcp --debug

El servidor se comunica mediante el Protocolo de contexto de modelo (MCP) y se puede acceder a él mediante HTTP o WebSockets cuando se ejecuta con FastMCP.

Herramientas disponibles

open_session : Abrir una nueva sesión de WhatsApp
send_message : Envía un mensaje a un chat
get_chats : Obtener una lista de chats
create_group : Crea un nuevo grupo de WhatsApp
get_group_participants : Obtener los participantes de un grupo

Referencia de la API de FastMCP

El servidor MCP de WhatsApp utiliza FastMCP para proporcionar puntos finales WebSocket y HTTP:

WebSocket: ws://localhost:8000/mcp
HTTP: http://localhost:8000/mcp

Puedes probar la API directamente usando herramientas como 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": {}}'

Cómo agregarlo a Claude Code

Para agregar un servidor de WhatsApp a Claude, use el comando claude mcp add :

# 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

Usando con Claude

Una vez que el servidor MCP de WhatsApp esté en funcionamiento, podrás interactuar con él usando Claude en tus conversaciones:

Autenticación con WhatsApp

Login to WhatsApp

Enviando un mensaje

Send the "Hello" message to John Doe

Uso con Claude Desktop

Para utilizar el servidor MCP de WhatsApp con Claude Desktop, debes agregarlo a tu archivo claude_desktop_config.json :

Usando la instalación pip (recomendado)

"mcpServers": {
  "whatsapp": {
    "command": "python",
    "args": ["-m", "whatsapp_mcp"]
  }
}

Usando el ejecutable

"mcpServers": {
  "whatsapp": {
    "command": "whatsapp-mcp"
  }
}

Usando 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"]
  }
}

Recuerde configurar sus credenciales de GreenAPI como variables de entorno o en su archivo .env antes de iniciar Claude Desktop.

Opciones de línea de comandos

El servidor MCP de WhatsApp acepta estos argumentos de línea de comandos:

--debug : Aumenta el nivel de verbosidad para la depuración
--host : Host al que vincular el servidor (predeterminado: 127.0.0.1)
--port : Puerto al que vincular el servidor (predeterminado: 8000)

Depuración

Para depurar el servidor MCP:

Utilice el inspector MCP: npx @modelcontextprotocol/inspector whatsapp-mcp
Ver registros en el directorio de registros de Claude Desktop (normalmente ~/Library/Logs/Claude/ en macOS)
Acceda a la interfaz web de FastMCP en http://localhost:8000 para obtener documentación de API interactiva

Desarrollo

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8 src/

# Run type checking
mypy src/

El proyecto utiliza una configuración moderna pyproject.toml que incluye:

Dependencias básicas necesarias para ejecutar la aplicación
Dependencias de desarrollo disponibles con pip install -e ".[dev]"

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

WhatsApp MCP Server