QQbot-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@QQbot-MCP 在 QQ 群 GROUP_OPENID 里发消息说“大家好”"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
QQbot-MCP
把 QQ 官方机器人 OpenAPI 封装成 MCP 服务和中文交互式 CLI。不记接口路径,也能在终端或 Agent 里发消息、管理群/频道、上传文件、接收事件。
社区实现,不是腾讯官方产品。QQ API 可能调整,升级前请关注 覆盖清单。
关于
把 QQ 官方机器人 OpenAPI 封装成 MCP 服务和中文命令行工具。
终端里直接发消息、回复、管理群/频道、上传文件、接收事件。
MCP 客户端里用同一套工具;没有凭据时只查文档,配置后可读写。
CLI 启动即显示二维码、机器人创建/登录链接和二维码图片路径。
Related MCP server: qq-mcp-server
安装
要求 Node.js >= 22。
npm 全局安装
npm install -g qqbot-mcp
qqbot-mcp --version直接运行
npx -y qqbot-mcp源码安装
git clone https://github.com/Pheobe-Southwood/qqbot-mcp.git
cd qqbot-mcp
pnpm install
npm run build
sudo ./deploy/install.sh完整安装说明见 docs/INSTALL.md。
配置
最少填 AppID 和 AppSecret:
QQBOT_APP_ID=102xxxxxx
QQBOT_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
QQBOT_MCP_MODE=readAppID/AppSecret 在 QQ 开放平台 的机器人「开发设置」中获取,步骤见 docs/CREDENTIALS.md。
本机安装后编辑
/etc/qqbot-mcp.env(权限600)。MCP 客户端可把变量写进
env。完整变量表见 docs/CONFIGURATION.md。
使用
交互式 CLI
qqbot-mcp启动后会显示二维码、链接、PNG 路径,然后进入 qqbot>:
扫码创建/连接 QQ 机器人:
https://q.qq.com/qqbot/openclaw/login.html?redirect_url=...
二维码图片:/tmp/qqbot-mcp-qr-xxxx/qqbot-mcp-qr-xxxx.png
qqbot> send group GROUP_OPENID 大家好
qqbot> events start websocket
qqbot> exit常用命令:
命令 | 作用 |
| 查看全部命令 |
| 运行状态 |
| 重新生成二维码 |
| 查 API |
| 向导式发消息 |
| 向导式被动回复 |
| 事件流 |
| 打印 MCP 客户端配置 |
| 退出 |
完整命令和示例见 docs/CLI.md。
在 MCP 客户端中使用
{
"mcpServers": {
"qqbot": {
"command": "npx",
"args": ["-y", "qqbot-mcp", "--mcp"],
"env": {
"QQBOT_APP_ID": "102xxxxxx",
"QQBOT_APP_SECRET": "replace-me",
"QQBOT_MCP_MODE": "read"
}
}
}
}本机安装也可以写:
{
"mcpServers": {
"qqbot": {
"command": "/usr/local/bin/qqbot-mcp",
"args": ["--mcp"]
}
}
}无参数且不在终端运行时,会自动按 MCP 运行,兼容旧配置。
二维码
默认内容:QQ 机器人快速创建/登录入口。
qqbot-mcp --qr:只打印二维码/链接/图片路径后退出。--no-qr或QQBOT_MCP_QR=off:启动时跳过。QQBOT_MCP_QR_URL:换成自定义邀请链接。二维码不会包含 AppSecret,也不会自动绑定机器人。
文档
许可证
MIT,见 LICENSE。
Available Tools
13 toolsbot_statusARead-onlyIdempotent
Show local runtime status: mode, credential/token presence (never the token), catalog version, event buffer, gateway/webhook state. Optionally probe QQ with get_gateway_bot.
Inputs: probe_network.
clear_eventsADestructiveIdempotent
Drop all buffered events without stopping the transport. Useful after testing.
Inputs: no named parameters.
download_attachmentBRead-only
Download an attachment URL (message image/file, media URL) into QQBOT_MCP_DOWNLOAD_DIR with size cap and SSRF guard. Returns a local path for further processing.
Inputs: url (required), filename, max_bytes.
event_stream_statusARead-onlyIdempotent
Show event transport configuration plus gateway, webhook and buffer status.
Inputs: no named parameters.
get_apiARead-onlyIdempotent
Get the full documentation for one API: path/query/body schemas, response fields, error codes, rate limits and examples. Call this before invoke_api for non-trivial bodies.
Inputs: name (required).
get_event_typeARead-onlyIdempotent
Get one event payload schema, required intents and examples (e.g. C2C_MESSAGE_CREATE, GROUP_AT_MESSAGE_CREATE).
Inputs: name (required).
list_apisARead-onlyIdempotent
List QQ bot APIs from the local catalog (103 endpoints, 21 categories). Filter by category, keyword or read/write. This is the first call to discover what the bot can do.
Inputs: keyword, category, read_only, include_legacy.
list_categoriesARead-onlyIdempotent
List catalog categories with endpoint counts.
Inputs: no named parameters.
list_event_typesARead-onlyIdempotent
List QQ gateway/webhook event types (53), optionally filtered by intent or category. Use get_event_type for payload fields.
Inputs: intent, keyword, category.
poll_eventsARead-only
Read buffered gateway/webhook events. Consumes returned events by default; pass peek=true to keep them. Requires event transport to be running.
Inputs: peek, limit, types, since_seq.
query_apiARead-only
Call a read-only QQ API (GET endpoints such as get_gateway_bot, list_groups, get_group_member). Read mode or higher. For writes use invoke_api.
Inputs: api (required), body, path, query.
search_apisARead-onlyIdempotent
Search APIs by Chinese/English keywords and return ranked matches with method, path and read-only flag.
Inputs: query (required), limit.
wait_eventsARead-only
Long-poll for new events (default 30s, max 5min). Returns buffered matches immediately, otherwise waits for a gateway/webhook event. Cancelled when the client aborts.
Inputs: peek, limit, types, since_seq, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have clearly distinct targets: catalog discovery (list_apis/get_api/search_apis/list_categories), event handling (poll_events/wait_events/get_event_type), and runtime status (bot_status/event_stream_status). The closest pair is poll_events vs wait_events, but descriptions clarify consume-vs-long-poll. A real ambiguity is introduced because query_api tells agents to 'use invoke_api' for writes, yet invoke_api is not in the set.
All names are snake_case and most follow a verb_noun pattern (query_api, list_apis, get_api, search_apis, poll_events, wait_events, download_attachment, clear_events). The two status tools (bot_status, event_stream_status) are noun-only, a minor but consistent deviation for state-readers.
13 tools is a reasonable scope for a catalog-plus-event-transport gateway server covering 103 endpoints and 53 event types. It is slightly heavy on event tools (six of thirteen), and the four catalog lookups (list_apis, search_apis, list_categories, get_api) border on redundant, but each earns a place.
The surface is read-only: query_api exists for GET calls and explicitly defers writes to invoke_api, which is absent, so the documented write path is a dead end. There is also no direct send-message or event-acknowledgement operation, leaving a major lifecycle gap for a bot API server.
Maintenance
Related MCP Connectors
Build and change Discord bots by describing them: slash commands, events, embeds, modals and data.
Read chats and members; send, edit and delete messages with a bot in Telegram.
Control your Discord community: send/read messages, manage channels and forums, and handle webhook…
MCP server for Sendbird — chat users, channels, members, and messages from your AI client.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables AI clients to send and receive QQ messages through NapCatQQ (OneBot v11) for both private and group chats. It supports message context management, real-time WebSocket listening, and human-like typing simulation.726MIT
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes QQ bot capabilities over Streamable HTTP, enabling clients to query bot status, read group and friend info, fetch chat history, and send group/private text messages.3MIT
- AlicenseAqualityCmaintenanceEnables interaction with QQ through official bot APIs or personal accounts bridged via NapCat/OneBot v11, including status checks, target listing, bounded context retrieval, and plain-text sending to allowlisted conversations.5MIT
- AlicenseAqualityCmaintenanceExposes NapCat/OneBot v11 QQ-bot APIs as MCP tools for any MCP client, and includes an LLM-driven QQ bot with memory, knowledge base, tool calling, web search, multimodal recognition, and permission controls.45MIT