MCP 集成

Ameba-Claw 通过两个独立的 CAP 模块支持 Model Context Protocol（MCP）：cap_mcp_client 让设备作为 MCP 客户端，接入外部 MCP Server 并将远程工具桥接为本地 Capability；cap_mcp_server 让设备充当 MCP Server，把自身能力以 MCP 协议对外开放，供外部 MCP 客户端（如 Claude Code）直接调用。两个方向相互独立，各自有对应的 Kconfig 选项，可单独启用。

模块	设备角色	典型场景
`cap_mcp_client`	MCP 客户端	调用运行在 PC、服务器或其他设备上的 MCP 工具
`cap_mcp_server`	MCP 服务端	让 Claude Code、AI IDE 等工具直接控制设备

MCP Client

cap_mcp_client 在设备联网后自动连接 vfs:/mcp/servers.json 中列出的所有外部 MCP Server，将发现的远程工具注册为设备本地 Capability。LLM 可以直接调用这些工具，与调用内置 Capability 没有区别。

工作流程

设备 Wi-Fi 连接成功后，cap_mcp_client 自动触发发现流程。
读取 vfs:/mcp/servers.json，逐一连接其中的服务器。
对每台服务器依次发送 initialize 握手请求和 tools/list 请求（MCP JSON-RPC 2.0 over HTTP POST）。
将返回的每个工具翻译为 claw_cap_descriptor_t 描述符（保留原始工具名、描述、输入 Schema）。
以 mcp_<服务器名> 为 group_id，将该服务器的所有工具批量注册到设备 Capability 系统。
LLM 在后续对话中可直接使用这些工具；调用时设备向对应服务器发送 tools/call 请求，并将结果返回给 LLM。

配置文件（servers.json）

配置文件位于 vfs:/mcp/servers.json，可通过 Web 后台"MCP 管理"面板编辑，也可在文件管理中直接修改。若文件不存在，设备首次启动时会自动创建一份空白模板。

格式示例：

{
  "servers": [
    {
      "name": "my-tools",
      "url": "http://192.168.1.100:3000/mcp",
      "api_key": "",
      "use_bearer": false
    }
  ]
}

字段	类型	说明
`name`	string（必填）	服务器标识，注册到 Capability 系统时 group_id 为 `mcp_<name>`，同时作为 Web 管理界面的显示名称
`url`	string（必填）	MCP Server 的 HTTP 端点地址，路径通常为 `/mcp`，例如 `http://192.168.1.100:3000/mcp`
`api_key`	string（可选）	鉴权密钥，留空则请求中不携带任何鉴权头
`use_bearer`	bool（可选）	`true`：请求头加 `Authorization: Bearer <api_key>`；`false`（默认）：以自定义头发送密钥

热更新（mcp_client_reload）

修改 servers.json 后无需重启设备。在对话中请 AI 调用 mcp_client_reload 工具，设备会卸载所有旧的 mcp_* cap 组并重新发现所有服务器。调用后会返回每台服务器的连接结果（成功/失败、发现的工具数量），便于排查配置问题。

也可以通过 AT 命令直接触发：

AT+CLAW=cap,mcp_client_reload

限制

最多同时配置 4 台 MCP Server，每台最多发现 8 个工具（总计上限 32 个）。
只支持 HTTP MCP Server（JSON-RPC 2.0 over HTTP POST），不支持 stdio 本地进程或 WebSocket 传输。
工具名在注册时保持远程原名，可通过工具名（AT+CLAW=cap,<tool_name>）或 group_id（mcp_<name>）引用。

备注

cap_mcp_client 的编译开关为 Kconfig 选项 CONFIG_CLAW_CAP_MCP_CLIENT，默认启用。

MCP Server

cap_mcp_server 在设备 HTTP Server 上注册 POST /mcp 端点，接受来自外部 MCP 客户端的 JSON-RPC 2.0 请求。外部工具可通过标准 MCP 协议直接调用设备能力，无需了解 Ameba-Claw 的任何内部接口。

暴露的工具

MCP Server 对外暴露以下工具：

工具名	说明
`rtk_device_state`	获取设备当前状态，包括 Wi-Fi 信息、堆内存使用、Agent 运行状态等
`rtk_router_trigger`	向设备事件路由发送事件，触发已配置的自动化规则。参数：event_type``（必填）、``text、`target_channel`、`payload_json`
`lua_run` / `lua_run_async` / `lua_job_get` 等	代理自设备 `lua` Capability 组，允许远程执行 Lua 脚本并获取结果

接入 Claude Code

在 Claude Code 的配置文件（~/.claude.json，Windows 下为 %APPDATA%\Claude\claude.json）中，找到当前 workspace 对应的层级，添加以下 mcpServers 配置（JSON 格式与其他 MCP 客户端一致）：

{
  "mcpServers": {
    "ameba-claw": {
      "type": "http",
      "url": "http://<设备 IP>/mcp"
    }
  }
}

保存后重启 Claude Code，即可在对话中直接使用设备工具。设备 IP 地址可在 Web 后台首页查询, Claude Code 需要与板子连接到同一个局域网才可以访问。

端点与服务名称

MCP Server 的默认端点为 /mcp，服务名称（serverInfo.name）默认为 ameba-claw。这两个值通过 cap_mcp_server_config_t 在初始化时指定，默认值定义在 cap_mcp_server.h 中：

#define CAP_MCP_SERVER_DEFAULT_ENDPOINT  "/mcp"

/* 默认配置，等效于：
   { .endpoint = "/mcp", .server_name = "ameba-claw" } */
cap_mcp_server_init(&CAP_MCP_SERVER_DEFAULT_CONFIG);

备注

cap_mcp_server 的编译开关为 Kconfig 选项 CONFIG_CLAW_CAP_MCP_SERVER，默认启用。

警告

/mcp 端点默认不要求鉴权，任何能访问设备 HTTP 端口的客户端都可以调用设备能力。其中 lua_run 工具允许执行任意 Lua 代码，请务必确认接入方的可信程度。若设备处于非受信网络，建议将其置于内网并避免对外暴露 HTTP 端口。