Remote OpenClaw
Menu

Wildfire Robot MCP Server

wildfirechat/wf-robot-mcp-server.ts
0 starsCommunity

Install to Claude Code

This server doesn't publish a one-line install command. Follow the setup in the source repository.

Summary

MCP server that wraps the Wildfire IM Robot SDK to provide tools for messaging, user management, group management, and file uploads, enabling AI agents to interact with Wildfire IM via natural language.

README.md

野火机器人 MCP Server

Wildfire Robot MCP Server — 将野火IM机器人 SDK 封装为 MCP (Model Context Protocol) 服务，供 AI 智能体（Agent）调用野火IM机器人接口。

功能特性

基于野火IM的 RobotService，提供以下功能的 MCP Tool 接口：

  • 消息：发送消息、回复消息、撤回消息、更新消息，以及便捷的文本/图片/文件消息接口
  • 用户：获取用户信息（通过用户ID/手机号/用户名）、搜索用户、获取好友列表、获取用户机器人列表
  • 资料：获取机器人资料
  • 群组：创建/解散/转让群组、修改群信息、成员管理（添加/踢出/禁言/管理员/别名等）
  • 文件上传：上传文件

共 34 个 MCP 工具。

安全说明

此 MCP 服务仅对接野火IM的 机器人 API（/robot/ 路径），机器人可执行的操作受 IM 服务端控制，权限范围有限。

关于认证

本 MCP 服务不需要额外的认证机制，因为每次调用工具时，请求参数中都包含了野火IM机器人的 robotId 和 robotSecret，由野火IM服务端负责鉴权。

⚠️ 部署到公网时必须使用 HTTPS：由于 robotId 和 robotSecret 随每个请求明文传输，如果通过 HTTP 部署在公网，凭证会被中间人截获。生产环境务必通过 HTTPS、VPN 或内网访问。

关于本地文件操作

以下工具涉及服务端本地文件系统，要求 MCP 服务与调用方在同一台机器上（或至少能访问相同的文件路径）：

  • upload_file
  • send_image_message / send_image_message_with_options 的 filePath 模式
  • send_file_message / send_file_message_with_options 的 filePath 模式

部署到远程服务器时：

  • filePath 模式不可用（客户端提供的本地路径在服务器上不存在）
  • 请改用 imageUrl / fileUrl 模式，传入可被 MCP 服务端访问的网络链接

不建议暴露管理 API

野火IM还提供 管理后台 API（/admin/ 路径），可用于创建用户、删除消息、销毁群组等高级操作。但管理 API 权限极大，一旦暴露给 AI Agent 使用，可能造成严重安全风险。强烈不建议将管理 API 暴露给 Agent，如果出错会造成很大危害。

如果需要管理 API 的 MCP 服务，可以参考本项目自行封装，但务必注意：

  • 管理密钥（admin secret）一旦泄露，整个 IM 服务将被控制
  • AI Agent 可能误解用户意图执行危险操作（如批量删用户、删消息）
  • 建议仅在内网可信环境使用，或对工具做严格的参数校验和白名单

一般情况下，使用本项目的 机器人 MCP 即可满足大多数业务需求。

快速开始

环境要求

  • Node.js >= 18
  • npm >= 8

安装

git clone <your-repo-url>
cd wf-robot-mcp-server.ts

# 安装依赖
npm install

# 构建
npm run build

配置

通过环境变量配置：

# 设置野火IM服务器地址（默认 http://localhost，端口80）
# 注意：机器人接口默认端口是80，不是18080（18080是管理后台端口）
export WF_IM_SERVER_URL=http://your-im-server

启动

支持两种运行模式：

1. stdio 模式（默认，适用于 Claude Desktop 等本地 Agent）

npm start
# 或直接运行编译后的文件
node dist/index.js

2. HTTP 模式（适用于部署在服务器上，供远程客户端连接）

# 设置端口，即启动 HTTP 服务
export WF_MCP_PORT=3100
npm start

启动后 MCP 服务监听在 http://localhost:3100/mcp，客户端可通过 Streamable HTTP 协议连接。

注意：HTTP 模式支持需要客户端实现 MCP Streamable HTTP 传输。本地 Agent（如 Claude Desktop）通常使用 stdio 模式，不需要 HTTP。

多会话支持

HTTP 模式下，每个 Agent 初始化时会分配独立的 Session ID，互不干扰：

  • 每个会话拥有独立的 McpServer 和 Transport 实例
  • 会话间完全隔离，一个 Agent 的调用不影响其他 Agent
  • 无效 Session ID 的请求会被拒绝（400）
  • 空闲会话超时（10分钟）后自动清理，防止内存泄漏

验证

stdio 模式验证

启动后可通过标准输入/输出与客户端通信：

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js 2>/dev/null

HTTP 模式验证

# 健康检查
curl http://localhost:3100/

# 初始化
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# 列出工具（需要带上 Initialize 返回的 Mcp-Session-Id）
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

自动化测试脚本

项目提供了 scripts/test-http.mjs，可自动验证 MCP 协议、工具注册以及各工具调用。

# 先启动 HTTP 模式服务（示例端口 3100）
WF_MCP_PORT=3100 npm start

# 另开终端，运行测试
npm test                    # 仅验证协议 + 34 个工具是否注册
npm test -- --port 3100     # 指定端口
npm run test:tools          # 测试所有工具调用（需配置凭证）

不带凭证时，脚本只验证健康检查、初始化、会话管理和工具列表。要测试实际工具调用，设置以下环境变量：

export WF_TEST_ROBOT_ID=your_robot_id
export WF_TEST_ROBOT_SECRET=your_robot_secret
export WF_TEST_TARGET_USER=existing_user_id      # 用于用户/消息相关工具
export WF_TEST_TARGET_GROUP=existing_group_id    # 用于群组只读工具
export WF_TEST_TARGET_MESSAGE_UID=123456         # 用于 reply/recall/update
export WF_TEST_IMAGE_URL=https://example.com/test.png
export WF_TEST_FILE_URL=https://example.com/test.txt
export WF_TEST_FILE_NAME=test.txt

测试写操作时，显式开启对应范围：

# 测试消息发送工具
npm test -- --send

# 测试群组创建/修改等（会在 IM 服务器上创建一个测试群组）
npm test -- --group

# 测试解散/踢人/转让等高风险群组操作
npm test -- --destructive

# 测试全部工具
npm run test:tools

安全提示：--destructive 会实际执行解散群组、踢出成员、转让群主等操作，请确保在测试环境使用。

API 接口说明

所有工具的前两个参数均为认证信息：

| 参数 | 类型 | 说明 | |------|------|------| | robotId | string | 机器人ID | | robotSecret | string | 机器人密钥 |

消息工具

send_message

发送消息。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型：0-单聊, 1-群聊, 2-聊天室, 3-频道, 4-客服 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | payload | string (JSON) | 消息内容JSON字符串 |

payload 示例：{"type":1,"searchableContent":"hello"}

reply_message

回复消息。

| 参数 | 类型 | 说明 | |------|------|------| | messageUid | number | 消息UID | | only2Sender | boolean | 是否只回复给发送者（默认false） | | payload | string (JSON) | 消息内容JSON字符串 |

recall_message

撤回消息。

| 参数 | 类型 | 说明 | |------|------|------| | messageUid | number | 消息UID |

update_message

更新消息内容。

| 参数 | 类型 | 说明 | |------|------|------| | messageUid | number | 消息UID | | payload | string (JSON) | 新的消息内容JSON字符串 |

便捷消息工具

send_text_message

发送文本消息（便捷接口，自动构造消息 payload）。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型：0-单聊, 1-群聊, 2-聊天室, 3-频道, 4-客服 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | text | string | 文本消息内容 |

send_image_message

发送图片消息，支持 MCP 服务端本地文件或网络图片 URL。自动生成缩略图并上传到 IM 服务器后发送。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | filePath | string | MCP 服务端本地图片路径（与 imageUrl 二选一）。远程部署时不可用 | | imageUrl | string | 网络图片 URL（与 filePath 二选一）。远程部署时请使用此参数 |

处理流程：

  • 本地图片：读取 MCP 服务端文件 → 生成缩略图 → 上传原图 → 发送图片消息
  • 网络图片：下载图片 → 生成缩略图 → 上传原图 → 发送图片消息

send_file_message

发送文件消息。MCP 服务端本地文件自动上传后发送，网络链接直接发送。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | filePath | string | MCP 服务端本地文件路径（与 fileUrl 二选一）。远程部署时不可用 | | fileUrl | string | 文件网络链接（与 filePath 二选一）。远程部署时请使用此参数 | | fileName | string | 文件名（fileUrl 模式下必填） | | fileSize | number | 文件大小，单位字节（可选） |

send_text_message_with_options

发送文本消息（便捷接口，可指定接收用户）。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | text | string | 文本消息内容 | | to_users | string (JSON) | 指定接收用户ID列表（可选），如 ["uid1","uid2"] |

send_image_message_with_options

发送图片消息（支持 MCP 服务端本地文件或网络图片 URL，可指定接收用户，自动生成缩略图并上传）。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | filePath | string | MCP 服务端本地图片路径（与 imageUrl 二选一）。远程部署时不可用 | | imageUrl | string | 网络图片 URL（与 imageUrl 二选一）。远程部署时请使用此参数 | | to_users | string (JSON) | 指定接收用户ID列表（可选） |

send_file_message_with_options

发送文件消息（MCP 服务端本地文件自动上传、网络链接直接发送，可指定接收用户）。

| 参数 | 类型 | 说明 | |------|------|------| | sender | string | 发送者用户ID | | conversation_type | number | 会话类型 | | conversation_target | string | 会话目标ID | | conversation_line | number | 会话线路（默认0） | | filePath | string | MCP 服务端本地文件路径（与 fileUrl 二选一）。远程部署时不可用 | | fileUrl | string | 文件网络链接（与 filePath 二选一） | | fileName | string | 文件名（fileUrl 模式下必填） | | fileSize | number | 文件大小，单位字节（可选） | | to_users | string (JSON) | 指定接收用户ID列表（可选） |

用户工具

get_user_info

通过用户ID获取用户信息。

| 参数 | 类型 | 说明 | |------|------|------| | userId | string | 用户ID |

get_user_info_by_mobile

通过手机号获取用户信息。

| 参数 | 类型 | 说明 | |------|------|------| | mobile | string | 手机号 |

get_user_info_by_name

通过用户名获取用户信息。

| 参数 | 类型 | 说明 | |------|------|------| | userName | string | 用户名 |

get_owner_friend_list

获取机器人 owner 的好友列表。

无额外参数。

search_user_by_display_name

根据昵称搜索用户。

| 参数 | 类型 | 说明 | |------|------|------| | keyword | string | 搜索关键词（用户昵称） |

get_user_robots

获取指定用户拥有的机器人列表。

| 参数 | 类型 | 说明 | |------|------|------| | userId | string | 用户ID |

资料工具

get_robot_profile

获取机器人资料。

群组工具

create_group

创建群组。

| 参数 | 类型 | 说明 | |------|------|------| | groupInfo | string (JSON) | 群组信息，如 {"name":"群名","portrait":"","type":0,"extra":""} | | members | string (JSON) | 成员列表（可选），如 [{"member_id":"uid","type":0,"alias":""}] | | memberExtra | string | 成员额外信息（可选） |

get_group_info

获取群组信息。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID |

dismiss_group

解散群组。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID |

transfer_group

转让群组。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | newOwner | string | 新群主用户ID |

modify_group_info

修改群组信息。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | type | number | 修改类型：0-群名, 1-群头像, 2-群extra, 3-群禁言, 4-群允许发言, 5-群类型, 6-群搜索类型, 7-群自动同意加入, 8-群加入权限 | | value | string | 新值 |

get_group_members

获取群组成员列表。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID |

get_group_member

获取群组成员信息。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberId | string | 成员用户ID |

add_group_members

添加群组成员。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | members | string (JSON) | 成员列表，如 [{"member_id":"uid1","type":0,"alias":""}] | | memberExtra | string | 成员额外信息（可选） |

set_group_manager

设置/取消群组管理员。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberIds | string (JSON) | 成员ID列表，如 ["uid1","uid2"] | | isManager | boolean | true-设置管理员, false-取消管理员 |

mute_group_member

禁言/取消禁言群组成员。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberIds | string (JSON) | 成员ID列表 | | isMute | boolean | true-禁言, false-取消禁言 |

allow_group_member

设置/取消群组成员发言权限。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberIds | string (JSON) | 成员ID列表 | | isAllow | boolean | true-允许发言, false-禁止发言 |

kickoff_group_members

踢出群组成员。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberIds | string (JSON) | 要踢出的成员ID列表 |

quit_group

机器人退出群组。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID |

set_group_member_alias

设置群组成员别名。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberId | string | 成员用户ID | | alias | string | 别名 |

set_group_member_extra

设置群组成员额外信息。

| 参数 | 类型 | 说明 | |------|------|------| | groupId | string | 群组ID | | memberId | string | 成员用户ID | | extra | string | 额外信息 |

文件上传工具

upload_file

上传 MCP 服务端本地文件 到 IM 服务器（传入服务端本地文件路径，自动完成预签名获取和上传）。

| 参数 | 类型 | 说明 | |------|------|------| | filePath | string | MCP 服务端本地文件路径，如 /path/to/image.png。远程部署时不可用 | | mediaType | number | 媒体类型（默认4-文件）：1-图片, 2-音频, 3-视频, 4-文件, 5-链接, 6-存储, 7-位置 | | contentType | string (可选) | 文件 Content-Type，不传则根据文件扩展名自动识别 |

⚠️ 此工具读取的是 MCP 服务端本地文件系统 上的文件，因此仅在 MCP 服务与客户端在同一台机器时可用。远程部署时请先将文件上传到可被服务端访问的位置，或使用 send_image_message / send_file_message 的 imageUrl / fileUrl 模式。

部署到服务器

MCP 服务支持部署到服务器上，通过 HTTP 供远程客户端连接。

⚠️ 公网部署务必使用 HTTPS：本服务不实现额外的认证层，机器人凭证 robotId / robotSecret 随每次工具调用明文传输。HTTP 部署在公网会导致凭证泄露。建议通过 Nginx/Caddy 等反向代理开启 HTTPS，或仅在 VPN/内网环境使用。

⚠️ 远程服务器不支持 filePath 模式：upload_file 以及 send_image_message / send_file_message 的 filePath 模式依赖 MCP 服务端本地文件系统。远程部署时，请让客户端使用 imageUrl / fileUrl 模式传入可被服务端访问的网络链接。

使用 PM2 守护进程

npm install -g pm2
WF_MCP_PORT=3100 WF_IM_SERVER_URL=http://your-im-server pm2 start dist/index.js --name wf-robot-mcp
pm2 save
pm2 startup

使用 nohup

nohup env WF_MCP_PORT=3100 WF_IM_SERVER_URL=http://your-im-server node dist/index.js > mcp.log 2>&1 &

使用 systemd（Linux）

创建 /etc/systemd/system/wf-robot-mcp.service：

[Unit]
Description=Wildfire Robot MCP Server
After=network.target

[Service]
Type=simple
User=nobody
Environment=WF_MCP_PORT=3100
Environment=WF_IM_SERVER_URL=http://your-im-server
ExecStart=/usr/bin/node /path/to/wf-robot-mcp-server.ts/dist/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable wf-robot-mcp
sudo systemctl start wf-robot-mcp

在常见 Agent 中配置使用

本地模式（stdio，默认）

对于本地 Agent（如 Claude Desktop），MCP 服务以子进程方式运行，通过 stdio 通信。

Claude Desktop

编辑 Claude Desktop 配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}

重启 Claude Desktop 后，即可在对话中使用野火机器人相关工具。

注意：机器人 API 端口默认是 80，不是 18080。18080 是管理后台端口，不要混淆。如果 IM 服务在本地，不设置 WF_IM_SERVER_URL 即可默认使用 http://localhost。

Cursor

在 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}

Windsurf

在 Windsurf 的 MCP 配置中添加：

{
  "mcpServers": {
    "wf-robot": {
      "command": "node",
      "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"],
      "env": {
        "WF_IM_SERVER_URL": "http://your-im-server"
      }
    }
  }
}

通用 MCP 客户端（如 mcp-cli）

使用 npx 或直接运行：

# 使用 npx
WF_IM_SERVER_URL=http://your-im-server npx /path/to/wf-robot-mcp-server.ts

# 或通过 MCP 客户端配置
mcp add wf-robot --cmd "node" --args "/path/to/wf-robot-mcp-server.ts/dist/index.js" --env WF_IM_SERVER_URL=http://your-im-server

### 使用 uvx（Python 生态）

如果通过 Python 的 MCP 客户端工具连接：

{ "mcpServers": { "wf-robot": { "command": "node", "args": ["/path/to/wf-robot-mcp-server.ts/dist/index.js"], "env": { "WF_IM_SERVER_URL": "http://your-im-server" } } } } ```

远程 HTTP 连接

如果 MCP 服务已部署到服务器（HTTP 模式），支持 HTTP 的 MCP 客户端可远程连接：

{
  "mcpServers": {
    "wf-robot": {
      "url": "http://your-server-ip:3100/mcp"
    }
  }
}

注意：不是所有 MCP 客户端都支持远程 HTTP 连接。Claude Desktop 等本地 Agent 仅支持 stdio 模式，需要在运行 MCP 服务的同一台机器上配置。

使用说明

  1. IM 服务地址：需配置可访问的野火IM服务器地址。如果 IM 服务在本地，可用 http://localhost；如果在远程，请替换为实际地址。
  2. 机器人认证：每次调用工具时，都需要提供 robotId 和 robotSecret。Agent 会要求用户提供这些信息。
  3. JSON 参数：部分工具的参数需要以 JSON 字符串形式传入（如消息 payload、群组信息等），Agent 会自动处理序列化。

开发

目录结构

src/
  index.ts         # MCP 服务主代码
  types.d.ts       # 类型声明
package.json       # 依赖和脚本
tsconfig.json      # TypeScript 配置

构建

npm run build

添加新工具

在 src/index.ts 中调用 registerTool() 函数即可添加新工具：

registerTool(server, "tool_name", "工具描述", {
  param1: z.string().describe("参数1说明"),
  param2: z.number().describe("参数2说明"),
}, async (args, _extra) => {
  return handleToolCall(args.robotId, args.robotSecret, async (service) => {
    // 调用 service 的对应方法
    return service.someMethod(args.param1, args.param2);
  });
});

许可证

MIT

Related MCP servers

Browse all →

Apify MCP

apify/actors-mcp-server

Browser & ScrapingOpen

AWS MCP Servers

awslabs/mcp

9,330 starsOpen

Axiom MCP

axiomhq/mcp-server-axiom

61 starsOpen

Azure MCP

Azure/azure-mcp

1,219 starsOpen

Browserbase MCP

browserbase/mcp-server-browserbase

3,383 starsOpen

Chroma MCP

chroma-core/chroma-mcp

570 starsOpen

Browse

MCP servers by category

Other2643AI & ML2284Search2091Developer Tools1127Vector & Memory1121Cloud & DevOps721Files & Docs719Databases704Finance & Payments701Browser & Scraping485Communication418Productivity355