Green API WhatsApp

green-api-mcp-gateway

• 俄语文档

支持渠道

指南与新闻

---

GREEN-API WhatsApp 的 MCP 网关。AI Agent（Claude Desktop、OpenClaw、Cursor 等）可通过 Model Context Protocol 使用 WhatsApp 发送消息、管理实例和接收通知。

功能

发送文本消息、URL 文件、位置、联系人和投票。转发和编辑消息。管理群组（创建、获取数据、添加／移除参与者）。检查电话号码是否支持 WhatsApp，获取联系人及其信息。获取实例状态和设置，以及用于授权的二维码。通过轮询或 HTTP 接收器接收传入通知。用于创建／删除实例的 Partner API。单个网关支持多个实例。提供常见场景（客户支持、群发）的提示词模板。支持 Prometheus 指标和 OpenTelemetry。

有关如何连接 MCP 服务的说明，请参阅我们的网站

架构

整洁架构（端口与适配器）：

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/server

需要 Go 1.25+。

传输方式与端点

服务支持四种传输方式，通过 server.transport（或 GREEN_API_TRANSPORT 环境变量）选择：

传输方式	端点（相对于 host:port）	使用场景
stdio	stdin/stdout	本地 CLI（Claude Desktop、Cursor）启动二进制文件。
sse	GET / (stream) + POST /message	旧版 MCP 客户端（仅支持 SSE）。
http	POST/GET /mcp	可流式传输的 HTTP（MCP 2025-03-26+）——新客户端的首选方式。
hybrid	/sse + /message 以及 /mcp，共用一个端口	公共服务：同时提供旧版 SSE 和可流式传输的 HTTP。

所有基于 HTTP 的传输方式还会公开以下端点：

• GET /health、GET /healthz — 健康检查（无需身份验证）
• GET /favicon.ico、GET /favicon.png — GREEN-API 图标

启用 auth.mode: proxy 时，还会添加 OAuth 2.0 PKCE 端点：

• GET /.well-known/oauth-authorization-server — RFC 8414 元数据
• GET /.well-known/oauth-protected-resource — RFC 9728 元数据
• GET /authorize — 面向浏览器的授权表单
• POST /token — 令牌交换

配置

通过 YAML 配置

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

通过环境变量配置

环境变量的优先级高于 YAML 配置：

以下变量适用于两种部署模式。凭据变量（GREEN_API_INSTANCE_ID、GREEN_API_TOKEN、GREEN_API_URL）仅适用于使用 auth.mode: config 的本地 stdio 运行。对于 HTTP 传输方式（sse 使用 /sse + /message、http 使用 /mcp，或 hybrid），请改用 auth.mode: proxy——凭据通过 HTTP 标头或内置 OAuth 流程提供，环境变量中的凭据会被忽略。

• GREEN_API_INSTANCE_ID — 实例 ID
• GREEN_API_TOKEN — API 令牌
• GREEN_API_URL — API 基础 URL（默认为 https://api.green-api.com）
• GREEN_API_TRANSPORT — 传输方式：stdio、sse、http 或 hybrid
• GREEN_API_PORT — HTTP 端口（默认为 8090）
• GREEN_API_BASE_URL — 公共基础 URL（用于 OAuth 颁发者/重定向，例如 https://mcp.example.com）
• GREEN_API_WIDGET_DOMAIN — ChatGPT Apps 提交元数据所用的唯一小组件来源（默认为 GREEN_API_BASE_URL，其次为 https://mcp.green-api.com）
• GREEN_API_AUTH_MODE — config 或 proxy
• GREEN_API_AUTH_CACHE_TTL — 代理身份验证凭据缓存 TTL（秒）
• GREEN_API_WEBHOOK_MODE — polling 或 receiver
• LOG_LEVEL — 日志级别
• LOG_FORMAT — text 或 json

运行

# 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.yaml

集成

Claude Desktop（本地 stdio）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/green-api-mcp-gateway",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

OpenClaw

mcp:
  servers:
    - name: whatsapp
      command: /path/to/green-api-mcp-gateway
      args: ["--config", "/path/to/config.yaml"]

Docker

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

MCP 工具

消息

文档链接

• whatsapp_send_message — 文本消息
• whatsapp_send_file — 通过 URL 发送文件
• whatsapp_send_location — 位置
• whatsapp_send_contact — 联系人（vCard）
• whatsapp_send_poll — 投票
• whatsapp_forward_messages — 转发
• whatsapp_edit_message — 编辑
• whatsapp_delete_message — 删除

实例

文档链接

• whatsapp_get_state — 授权状态
• whatsapp_get_settings — 当前设置
• whatsapp_set_settings — 更新设置
• whatsapp_get_qr — 授权二维码
• whatsapp_connect — 连接实例
• whatsapp_disconnect — 断开实例

联系人

文档链接

• whatsapp_get_contacts — 联系人列表
• whatsapp_get_contact_info — 联系人信息
• whatsapp_check_whatsapp — 检查电话号码

群组

查看文档

• whatsapp_create_group — 创建群组
• whatsapp_get_group_data — 获取群组数据
• whatsapp_add_group_participant — 添加参与者
• whatsapp_remove_group_participant — 移除参与者
• whatsapp_leave_group — 退出群组

通知

查看文档

• whatsapp_receive_notification — 接收传入通知（长轮询）

Partner API

查看文档

• whatsapp_create_instance — 创建实例
• whatsapp_delete_instance — 删除实例
• whatsapp_get_instances — 列出实例

MCP 资源

• whatsapp://instance/{id}/state — 实例状态
• whatsapp://instance/{id}/settings — 实例设置

MCP 提示词

• whatsapp_customer_support — 客户支持模板
• whatsapp_broadcast — 广播消息模板

依赖项

• 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/server

许可证

MIT — 参见 LICENSE。