MCP gateway for GREEN-API WhatsApp. Lets AI agents (Claude Desktop, OpenClaw, Cursor, and others) send messages, manage instances, and receive notifications via WhatsApp using the Model Context Protocol.
Send text messages, files by URL, locations, contacts, polls. Forward and edit messages. Manage groups (create, fetch data, add/remove participants). Check phone numbers for WhatsApp, fetch contacts and their info. Get instance state and settings, QR code for authorization. Receive incoming notifications via polling or an HTTP receiver. Partner API for creating/deleting instances. Multi-instance support in a single gateway. Prompt templates for common scenarios (customer support, broadcasts). Prometheus metrics and OpenTelemetry.
Instructions for connecting the MCP server can be found on our website
Clean Architecture (Ports & Adapters):
cmd/server/main.go — entry point, DI wiring
internal/
domain/ — business entities, errors, constants (zero dependencies)
application/ — ports (interfaces)
infrastructure/
auth.go — CredentialManager (in-memory credential store)
config/config.go — YAML + env configuration
greenapi/client.go — WhatsApp client via Go SDK
mcp/
server.go — MCP server (stdio/sse)
tools.go — MCP tools registration
resources.go — MCP resources
prompts.go — MCP prompts
webhook/
bridge.go — polling bridge
receiver.go — HTTP receiver
go build -o green-api-mcp-gateway ./cmd/serverRequires Go 1.25+.
The server supports four transports, selected via server.transport (or the GREEN_API_TRANSPORT env var):
| Transport | Endpoints (relative to host:port) |
Use case |
|---|---|---|
stdio |
stdin/stdout | Local CLIs (Claude Desktop, Cursor) launching the binary. |
sse |
GET / (stream) + POST /message |
Legacy MCP clients (SSE only). |
http |
POST/GET /mcp |
Streamable HTTP (MCP 2025-03-26+) — preferred for new clients. |
hybrid |
/sse + /message and /mcp on one port |
Public server: serves both legacy SSE and Streamable HTTP. |
All HTTP-based transports also expose:
GET /health,GET /healthz— health probes (no auth)GET /favicon.ico,GET /favicon.png— GREEN-API icon
When auth.mode: proxy is enabled, the OAuth 2.0 PKCE endpoints are added too:
GET /.well-known/oauth-authorization-server— RFC 8414 metadataGET /.well-known/oauth-protected-resource— RFC 9728 metadataGET /authorize— browser-facing authorization formPOST /token— token exchange
server:
transport: stdio # stdio | sse | http | hybrid
port: 8090
auth:
mode: config # config | proxy
cache_ttl: 300 # seconds (proxy mode only)
green_api:
instances:
- id: 1101000001
api_token: "YOUR_TOKEN"
api_url: "https://api.green-api.com"
webhook:
mode: polling
polling_timeout: 20
rate_limit:
requests_per_second: 10
burst: 20
logging:
level: info
format: textEnvironment variables take precedence over the YAML config:
The variables below cover both deployment modes. Credentials variables (GREEN_API_INSTANCE_ID, GREEN_API_TOKEN, GREEN_API_URL) apply only to local stdio runs with auth.mode: config. For HTTP transports (sse on /sse + /message, http on /mcp, or hybrid) use auth.mode: proxy instead — credentials arrive in HTTP headers or via the built-in OAuth flow and the env credentials are ignored.
GREEN_API_INSTANCE_ID— instance IDGREEN_API_TOKEN— API tokenGREEN_API_URL— API base URL (defaults tohttps://api.green-api.com)GREEN_API_TRANSPORT— transport:stdio,sse,http, orhybridGREEN_API_PORT— HTTP port (defaults to8090)GREEN_API_BASE_URL— public base URL (used for OAuth issuer/redirects, e.g.https://mcp.example.com)GREEN_API_WIDGET_DOMAIN— unique widget origin for ChatGPT Apps submission metadata (defaults toGREEN_API_BASE_URL, thenhttps://mcp.green-api.com)GREEN_API_AUTH_MODE—configorproxyGREEN_API_AUTH_CACHE_TTL— proxy-auth credential cache TTL (seconds)GREEN_API_WEBHOOK_MODE—pollingorreceiverLOG_LEVEL— log levelLOG_FORMAT—textorjson
# With environment variables
export GREEN_API_INSTANCE_ID=1101000001
export GREEN_API_TOKEN=your_token
./green-api-mcp-gateway
# With a config file
./green-api-mcp-gateway --config config.yamlAdd to claude_desktop_config.json:
{
"mcpServers": {
"whatsapp": {
"command": "/path/to/green-api-mcp-gateway",
"args": ["--config", "/path/to/config.yaml"]
}
}
}mcp:
servers:
- name: whatsapp
command: /path/to/green-api-mcp-gateway
args: ["--config", "/path/to/config.yaml"]docker build -t green-api-mcp-gateway .
docker run --rm -i \
-e GREEN_API_INSTANCE_ID=1101000001 \
-e GREEN_API_TOKEN=your_token \
green-api-mcp-gatewaywhatsapp_send_message— text messagewhatsapp_send_file— file by URLwhatsapp_send_location— locationwhatsapp_send_contact— contact (vCard)whatsapp_send_poll— pollwhatsapp_forward_messages— forwardwhatsapp_edit_message— editwhatsapp_delete_message— delete
whatsapp_get_state— authorization statewhatsapp_get_settings— current settingswhatsapp_set_settings— update settingswhatsapp_get_qr— authorization QR codewhatsapp_connect— connect instancewhatsapp_disconnect— disconnect instance
whatsapp_get_contacts— contact listwhatsapp_get_contact_info— contact informationwhatsapp_check_whatsapp— phone number check
whatsapp_create_group— create a groupwhatsapp_get_group_data— group datawhatsapp_add_group_participant— add a participantwhatsapp_remove_group_participant— remove a participantwhatsapp_leave_group— leave a group
whatsapp_receive_notification— receive an incoming notification (long-poll)
whatsapp_create_instance— create an instancewhatsapp_delete_instance— delete an instancewhatsapp_get_instances— list instances
whatsapp://instance/{id}/state— instance statewhatsapp://instance/{id}/settings— instance settings
whatsapp_customer_support— template for customer supportwhatsapp_broadcast— template for broadcast messaging
- mcp-go — MCP SDK
- whatsapp-api-client-golang — GREEN-API Go SDK
go test ./...
gofmt -w .
GOOS=linux GOARCH=amd64 go build -o green-api-mcp-gateway-linux ./cmd/serverMIT — see LICENSE.