> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务器

> 让 AI 代理人通过 GOWA 内置的模型上下文协议端点在 /mcp 使用 WhatsApp

GOWA服务于与REST API相同进程的 [Model Context Protocol](https://modelcontextprotocol.io) 端点。 任何支持 **简化HTTP** 传输的 MCP 客户端可以通过它发送消息、阅读聊天并管理群组。

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (默认 `http://localhost:3000/mcp`)
* 默认启用。使用 `MCP_ENABLED=false` 或 `--mcp-enabled=false` 禁用。
* 无状态：没有会话握手以保持通话之间的存活。

> [!NOTE]
>
> 从旧版本升级？独立的 `./whatsapp mcp` 命令及其位于端口 8080 的 SSE 端点（`/sse`）已被移除。请运行 `./whatsapp rest`，并将客户端指向 `/mcp`。原先每项操作对应一个工具的工具集已替换为下方的整合工具。

## 连接客户端

`/mcp` 与 REST API 使用相同的 Basic Auth 认证。请发送 `Authorization` 请求头；如果运行多个设备，还需发送 `X-Device-Id`：

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=` 是 `base64("admin:changeme")` 的结果；使用 `echo -n 'user:pass' | base64` 生成自己的值。如果未启用 Basic Auth，可省略 `Authorization`；如果只有一个设备，可省略 `X-Device-Id`。

具体的配置格式取决于客户端。如果客户端只能启动 stdio 服务器，请使用 `mcp-remote` 等桥接工具。

## 工具

GOWA 暴露了7个工具。每个工具都需要一个选择操作的 `type` (send) 或 `action` (所有其他) 参数。

| 工具 | `type` / `action` |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`, `get`, `pause`, `resume`, `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`, `list_contacts`, `get_messages`, `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

关于参数的说明：

* `whatsapp_send` 总是需要 `type` 和 `phone` 。媒体\*\*只能通过 URL 发送(`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP 无法上传本地文件。 `link` 需要`link` 和 `caption`；`forward` 需要`message_id`。
* `whatsapp_send` 接受[定时发送字段](https://gowa-docs.mintlify.site/zh/examples/scheduled-sends.md)（`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`）。使用 `whatsapp_schedule` 管理生成的计划（`get`、`pause`、`resume` 和 `cancel` 需要 `schedule_id`）。
* `whatsapp_message` 需要 `phone` (聊天)和`message_id`; `edit` 也需要 `message` 。
* 在 v9.9.0 之后的 GOWA `main` 分支中，使用 `action: "edit"` 的 `whatsapp_message` 支持通过 `media_type: "image"` 或 `media_type: "document"` 替换说明文字。媒体类型须与原始媒体一致，并省略 `link`。参见[编辑说明文字](https://gowa-docs.mintlify.site/zh/examples/sending-messages.md#%E7%BC%96%E8%BE%91%E5%9B%BE%E5%83%8F%E6%88%96%E6%96%87%E6%A1%A3%E6%A0%87%E9%A2%98)。
* `whatsapp_chat`: `get_messages` 需要 `chat_jid`; `archive` 需要 `chat_jid` 和 `archived`。
* `whatsapp_app`: `login_code` 需要 `phone` 。

实验按钮、位置请求和旋转轮播送只能通过 REST 提供。请参阅[交互消息](https://gowa-docs.mintlify.site/zh/examples/interactive-messages.md)。 通讯工具支持频道发现、历史计数器和自动续订实时更新订阅。见 [newsletters](https://gowa-docs.mintlify.site/zh/examples/newsletters.md)。

媒体URL下载应用相同的公共地址检查，无需使用 `HTTP_PROXY` 或 `HTTPS_PROXY` 直接发送和连接。 从本地文件上传需要REST API。

您的 MCP 客户端显示每个工具的完整输入模式。HTTP 端点接受POST 和 DELETE. GET SSE 已禁用。

## 设备选择

每个通话按此顺序解析其设备：

1. 工具调用上的 `device_id` 参数。
2. MCP 连接上的 `X-Device-Id` 头部。
3. 唯一的注册设备，如果确有一个设备存在。

否则通话无法使用 `device identification required: set the X-Device-Id header or pass device_id` 。请见 [Multi-device](https://gowa-docs.mintlify.site/zh/concepts/multidevice.md)。

## 使用 OAuth 的远程客户端

托管客户端，如Claude 自定义连接器不能附加基本认证头部。 对于他们，GOWA可以运行 `/mcp` 的 OAuth 2.1 授权服务器。默认情况下是关闭的。

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

要求和行为：

* `APP_BASIC_AUTH` 必须设置：授权页面在这些账户中标记用户。没有授权页面启动失败。
* 发行者和资源必须是 \*\*public HTTPS \*\* URLs 客户端，没有像`http://gowa:3000`这样的内部地址。
* 通过 OAuth 开启，`/mcp` 可以接受一个 **或** 基本认证。在REST 或UI 路由上不接受令牌。
* 客户端注册(RFC 7591)，注册机构限制在16KiB，每次重定向到2KiB。 注册次数限于每小时40次，储存1 000个客户；未使用客户在24小时后打印。
* PKCE `S256` 是强制性的。 代码在5分钟后过期，在1小时后访问令牌；刷新令牌旋转，重用旧令牌撤销整个令牌家庭。 在`MCP_OAUTH_DB_URI`中只存储令牌的 SHA-256 哈希值(默认 `file:storages/oauth.db`).

重定向 URI 必须与注册值完全一致。原生客户端可以使用带动态端口的 HTTP 环回 IP 回调。`localhost` 回调必须明确指定端口并完全匹配。其他重定向必须使用 HTTPS。OAuth `resource` 绑定到规范 MCP URL；令牌请求可以省略它，但如果提供，其值必须匹配。授权成功的响应包含 `iss`。

在 OAuth 写入过程中打印过期的代码和代币。 旋转的刷新令牌哈希仍然存在，需要检测是否对一个在线家庭进行重放，最多持续30天的刷新令牌。 删除或替换 OAuth 数据库使现有客户端和赠款无效。

相对于签发者地址的端点：`/oauth/authorize`、`/oauth/token`、`/oauth/register`。发现元数据使用在域名根目录插入 well-known 路径的 URL，因此设置 `APP_BASE_PATH=/gowa` 时，代理必须路由以下路径：

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

检查来自外部的发现：

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

然后添加 `https://gowa.example.com/mcp` 作为自定义连接器，然后使用 `APP_BASIC_AUTH` 账户登录。

> [!WARNING]
>
> 确保在 GOWA 前面的 Cloudflare Access 、 bot 挑战或认证代理不会拦截众所周知的 `/oauth/*` 或 `/mcp` 路径。 在代理服务器的`/oauth/authorize`上的比率限制失败。


## Related topics

- [预定发送](https://gowa-docs.mintlify.site/zh/examples/scheduled-sends.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/zh/index.md)
- [API 参考](https://gowa-docs.mintlify.site/zh/api-reference/introduction.md)
- [API 认证](https://gowa-docs.mintlify.site/zh/api-reference/authentication.md)
- [配置引用](https://gowa-docs.mintlify.site/zh/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.