Skip to main content
Glama
wanwujiehuyi-web

qq-mcp-bridge

by wanwujiehuyi-web
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

qq-mcp-bridge

把 QQ 官方机器人（bot.q.qq.com）接入 DeepSeek Harness 的 MCP 桥。

只做两件事：

能力

说明

私聊收发

用户私聊机器人 → 消息落到本地队列 → DSH 用 fetch_messages 取走，用 send_private_message 回复

主动推送

DSH 随时可调 send_private_message（不传 msg_id），用于任务完成、定时提醒

不包含群聊消息。需要群聊请自行增加 send_group_message 工具，并注意每个工具 schema 都会进入每次模型请求。

需要什么

  1. 在 QQ 开放平台 注册开发者、创建机器人并通过审核；

  2. 记下 AppID、ClientSecret（WebSocket 鉴权用；不是 QQ 密码）；

  3. Node.js >= 22.4；

  4. 本机网络能访问 api.bot.qq.com。

Related MCP server: qq-onebot-mcp

安装（DSH bundle）

npx -p @deepseek-ai/dsh dsh plugin --profile web add qq-mcp-bridge@0.1.0

重启 DSH 后，工具以 mcp__qq__* 出现。

包通过 cordis.patch.yml 注册 @deepseek-ai/dsh-mcp-client：

- insert:
    - id: qq-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: qq
        transport: stdio
        command: npx
        args: ['-y', '-p', 'qq-mcp-bridge@0.1.0', 'qq-mcp-bridge']

配置（不要把 AppSecret 提交进 Git）

复制示例：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.qq-mcp-bridge" | Out-Null
Copy-Item .\config.example.json "$env:USERPROFILE\.qq-mcp-bridge\config.local.json"

编辑 %USERPROFILE%\.qq-mcp-bridge\config.local.json：

{
  "appId": "你的 AppID",
  "clientSecret": "你的 ClientSecret",
  "appToken": "",
  "apiBase": "https://api.bot.qq.com"
}

读取顺序：

  1. QQ_CONFIG_FILE 指定的文件；

  2. 包根目录的 config.local.json；

  3. %USERPROFILE%\.qq-mcp-bridge\config.local.json。

也支持环境变量 QQ_BOT_APPID / QQ_BOT_CLIENT_SECRET / QQ_BOT_APP_TOKEN，但 DSH 启动 MCP 子进程时会清洗含 SECRET/TOKEN 的父环境变量，所以最稳的是本地 config.local.json，或在 DSH profile 的 env 块显式注入。

没有凭证时服务自动进入 mock 模式：不发网络请求，可用于验证 MCP 协议。

工具

工具

用途

mcp__qq__fetch_messages

取用户发来的待处理私聊消息

mcp__qq__send_private_message

回复；带 msg_id 为被动回复，不带则为主动推送

mcp__qq__bot_info

查看机器人身份、mock/网关状态、待处理队列、已知联系人

主动推送需要 user_openid。它只能从对方发来的消息里获得；QQ 不提供“按 QQ 号查 openid”。同一个用户在不同机器人下的 openid 不同。

本地运行 / 自检

node src/mcp-server.js        # stdio MCP
node src/doctor.js            # 配置与连通性诊断
npm test                      # selftest + gateway 状态机测试

Waker 插件（可选，本机 profile 使用）：

- insert:
    - id: qq-waker
      name: '<qq-mcp-bridge 包路径>/waker/index.js'
      config:
        sessionId: '<目标 DSH 会话 ID>'
        bridgeDir: '<qq-mcp-bridge 包路径>'
        env:
          QQ_BOT_APPID: '<你的 AppID>'
          QQ_BOT_CLIENT_SECRET: '<你的 ClientSecret>'

Waker 会持有 WebSocket，将入站消息直接注入指定会话；如果只用 MCP 工具，不需要它。

安全边界

  • 本仓库不包含任何真实 AppID/AppSecret/openid/会话 ID；

  • state/、config.local.json、日志、测试抓包已被 .gitignore 排除；

  • 消息队列和联系人只写本机；

  • 只支持 QQ 官方机器人私聊，不读取个人 QQ 协议，不模拟登录。

License

MIT

Available Tools

3 tools
bot_infoA

查询 QQ 机器人自身信息与桥接状态：机器人身份、是否处于 mock 模式、网关连接状态、待处理消息条数。用于排查配置问题。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full burden, and it does disclose the concrete informational content an agent will receive (mock-mode flag, gateway connectivity, pending-message backlog). The query verb implies a side-effect-free read, though permissions and any side effects are never stated explicitly. For a parameterless diagnostic read this is adequate disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first front-loads what is queried and the fields exposed, the second supplies the use case. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple parameterless info tool with no annotations and no output schema, the description is nearly complete—it enumerates the return content that the missing output schema would otherwise supply (mock mode, gateway status, pending count) and gives the troubleshooting context. Only explicit read-only/no-side-effect wording is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to elaborate. No misleading parameter hints are present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (查询/query) and resource (the QQ bot's own info and bridge status), then enumerates the exact fields returned: identity, mock mode, gateway connection, pending message count. This clearly separates it from the sibling tools send_private_message and fetch_messages, which handle message I/O rather than self-diagnostics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"用于排查配置问题" gives a clear context for using the tool (configuration troubleshooting), which is more than nothing. However it names no alternatives and gives no when-not conditions or prerequisites, so the guidance stays at the implied-usage level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_messagesA

取出 QQ 用户发给机器人的待处理单聊消息。消息由后台 WebSocket 网关接收并排队，本工具只读取队列。队列为空是正常情况，说明当前没有新消息。

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo最多取几条，默认 10。
consumeNo是否在读取后从队列移除，默认 true。设为 false 只窥视不移除，便于重复查看。

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It adds useful architecture context (WebSocket gateway queues messages; this tool only reads them) and sets expectations for empty results, but it omits the key side effect documented only in the schema: consume defaults to true, so reads remove messages from the queue by default. Saying '只读取队列' while the default behavior is destructive is a meaningful understatement of impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, all front-loaded with the core action first, then the queue mechanics, then the empty-result caveat. Every sentence carries information an agent needs; there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-optional-parameter read tool with no annotations or output schema, the description conveys where messages come from, what reading means, and why an empty result is expected. It could go slightly further by describing the shape of a returned message or the polling expectation, but nothing critical to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (limit and consume are both documented with defaults and behavior), so the schema already does the work. The description adds no syntax, format, or default information beyond it, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('取出 QQ 用户发给机器人的待处理单聊消息') and narrows the scope with '本工具只读取队列', which cleanly separates it from the sibling send_private_message. An agent can tell what it returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating context: messages arrive via a backend WebSocket gateway and are queued, so this tool is the read path for them. It also warns that an empty queue is normal, preventing the agent from treating an empty result as a failure. It never names an alternative or exclusion explicitly, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_private_messageA

向指定 QQ 用户发送单聊消息。既可用于被动回复（传入刚才收到的 msg_id），也可用于主动推送（不传 msg_id，例如任务完成或定时提醒）。user_openid 与 msg_id 都来自 fetch_messages 或 bot_info 的返回值。

ParametersJSON Schema
NameRequiredDescriptionDefault
msg_idNo可选。要回复的那条入站消息的 msg_id。传入即为被动回复，可绕过主动消息频率限制；不传即为主动推送。
contentYes消息文本内容。
user_openidYes接收者的用户 openid。同一用户在不同机器人下的 openid 不同，必须用 bot_info 的 contacts.known 或 fetch_messages 返回值；不要自己编造。

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the two behavioral modes, but the critical consequence – that passive replies bypass proactive-message rate limits – is buried in the msg_id schema description rather than the tool description, and failure modes (e.g., reply-window limits for proactive sends) are not disclosed at all.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with purpose followed by mode selection and parameter provenance; the final sentence partly duplicates the schema's parameter descriptions, which is the only thing keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, it covers the essentials: what it does, the two modes, and where required IDs come from. Missing rate-limit and delivery-failure context keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented; the description only adds that user_openid and msg_id originate from fetch_messages/bot_info returns, which is useful provenance but largely redundant with the schema's own wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('向指定 QQ 用户发送单聊消息') and immediately distinguishes the two operating modes (passive reply vs. proactive push), which is the key thing separating this from sibling read tools fetch_messages/bot_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the condition that selects each mode: pass msg_id for a reply to a just-received message, omit it for scheduled/proactive pushes with examples (task completion, reminders). No explicit 'when not to use' or named alternative tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedbot_info
    • First observedfetch_messages
    • First observedsend_private_message
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

The three tools cover three clearly distinct roles: sending a message, draining the inbound message queue, and inspecting bot/bridge status. There is no plausible way to confuse send_private_message with fetch_messages or bot_info, and the descriptions reinforce the send/receive/observe split.

Naming Consistency4/5

send_private_message and fetch_messages both follow a consistent snake_case verb_noun pattern and pair naturally as outbound/inbound counterparts. bot_info breaks the pattern by using a bare noun with no verb, which is a minor deviation but a readable one.

Tool Count4/5

Three tools is lean but appropriate for a thin WebSocket-to-MCP bridge whose job is just relay plus status. The surface is not padded, though it sits near the lower bound where an agent might want one or two more capabilities.

Completeness3/5

The core poll-then-reply loop is covered, but the surface stops at private chat: there is no group/conversation messaging, no media or non-text sending, no history or message-lookup beyond the live queue, and no acknowledgement semantics for processed messages. These are notable gaps for a general QQ bot bridge even if private-only was intentional.

Maintenance

ActivityNo data
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • astral-bridge

    oines
    A
    license
    B
    quality
    B
    maintenance
    Connects QQ via NapCat OneBot v11 to an Astral Code app-server, exposing MCP tools for sending messages, files, images, and fetching conversation history.
    10
    1
    Apache 2.0

  • qq-onebot-mcp

    HUliangwei
    F
    license
    A
    quality
    B
    maintenance
    Enables MCP hosts to bridge with QQ via NapCat/OneBot 11, allowing whitelisted private messages to reach an agent with full tool access while group mentions are answered by a sandboxed pure LLM without system access.
    8
    -

  • QQ MCP

    BK927
    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