Skip to main content
Glama

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=read

使用

交互式 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

常用命令:

命令

作用

help

查看全部命令

status

运行状态

qr

重新生成二维码

apis [关键词] / api <名称>

查 API

send

向导式发消息

reply

向导式被动回复

events status/start/stop/poll/wait

事件流

mcp

打印 MCP 客户端配置

exit / quit

退出

完整命令和示例见 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 tools
bot_statusA
Read-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_eventsA
DestructiveIdempotent

Drop all buffered events without stopping the transport. Useful after testing.

Inputs: no named parameters.

download_attachmentB
Read-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_statusA
Read-onlyIdempotent

Show event transport configuration plus gateway, webhook and buffer status.

Inputs: no named parameters.

get_apiA
Read-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_typeA
Read-onlyIdempotent

Get one event payload schema, required intents and examples (e.g. C2C_MESSAGE_CREATE, GROUP_AT_MESSAGE_CREATE).

Inputs: name (required).

list_apisA
Read-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_categoriesA
Read-onlyIdempotent

List catalog categories with endpoint counts.

Inputs: no named parameters.

list_event_typesA
Read-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_eventsA
Read-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_apiA
Read-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_apisA
Read-onlyIdempotent

Search APIs by Chinese/English keywords and return ranked matches with method, path and read-only flag.

Inputs: query (required), limit.

wait_eventsA
Read-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

    A3.6/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      7
      26
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT