AI导哈

QQ机器人桥接服务

通过MCP工具协议暴露QQ消息收发能力，让外部项目无需依赖QQ SDK即可接入QQ消息流。

  • by natsume37
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 natsume37/qq-bot-mcp

使用说明

qq_bot_MCP

基于 qq-botpy + MCP 的 QQ 机器人桥接服务。通过 MCP 工具协议暴露 QQ 消息收发能力，让外部项目无需依赖 QQ SDK 即可接入 QQ 消息流。

架构说明

  • qq_bot_mcp/config.py：配置加载（QQ 凭据）
  • qq_bot_mcp/models.py：数据模型（事件、回复结果）
  • qq_bot_mcp/adapters/qq_client.py：QQ 平台适配层（接收 AT/私信/C2C/群聊消息）
  • qq_bot_mcp/services/message_hub.py：协程消息总线（待处理事件队列、历史记录、回复分发）
  • qq_bot_mcp/mcp/server.py：MCP 工具层（暴露给 MCP 客户端调用）
  • qq_bot_mcp/runtime.py：运行时装配（QQ Bot 生命周期管理）
  • qq_bot_mcp/cli.py：CLI 入口

默认行为：只收消息不自动回复，由 MCP 客户端决定如何处理并回包。

依赖安装

uv sync

或：

pip install -e .

环境变量

在根目录创建 .env：

qq_bot_id=你的BotAppID
qq_bot_appsecret=你的BotSecret

运行方式

一体化（QQ Bot + MCP Server）

uv run qq-bot-mcp --mode all

仅 QQ Bot Runtime

uv run qq-bot-mcp --mode bot

仅 MCP Server（不启动 QQ Bot）

uv run qq-bot-mcp --mode mcp

MCP 工具清单

工具名 说明
qqbot_status 运行状态、待处理数量、累计消息数
qqbot_list_pending(limit) 拉取待处理事件
qqbot_wait_event(timeout_seconds) 阻塞等待一条新事件
qqbot_reply_event(event_id, ...) 按事件回复到 QQ（支持文本/图片/Markdown/Ark/Embed/Media）
qqbot_discard_event(event_id) 丢弃事件，不做回复
qqbot_list_history(limit) 查看最近历史消息
qqbot_capabilities 返回场景能力说明

MCP 客户端接入流程

  1. 以 stdio 方式启动本服务作为 MCP server
  2. 调用 qqbot_wait_event 或 qqbot_list_pending 获取消息
  3. 根据业务逻辑生成回复
  4. 调用 qqbot_reply_event(event_id, content=...) 回消息到 QQ

客户端实现由使用方自行完成。

测试

uv run pytest test/ -v

AI 客户端 Demo（DeepSeek）

已提供最小客户端示例：test/ai_chat_client_demo.py。

先在 .env 增加：

LLM_API_KEY=你的DeepSeekKey
LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_TIMEOUT=30

运行：

uv run python test/ai_chat_client_demo.py

相关 MCP