qq-bot-sender-mcp

一个面向个人 QQ 单聊场景的 MCP 服务，用来向好友发送文本、Markdown、图片和文件。

项目简介

qq-bot-sender-mcp 通过 MCP 协议封装 QQ 机器人私聊发送能力，适合这类场景：

• 把运行结果直接发到自己的 QQ
• 把截图、图片或文档推送到 QQ
• 在支持 MCP 的客户端里，通过工具调用完成消息发送

当前实现只支持个人单聊（C2C），不支持群聊。

如果这个项目对你有帮助，欢迎点个 Star 支持一下。

应用场景

• 任务跑完后，把处理结果自动发到自己的 QQ
• 做代码修改、数据处理或脚本执行后，把阶段进展同步到 QQ
• 截图、报表、文档、压缩包等产物生成后，直接推送到 QQ
• 测试、构建、验证完成后，把结果作为简短通知发到 QQ
• 需要人工确认下一步时，先发一条 QQ 提醒，再回来继续处理

支持能力

服务当前支持发送：

• 普通文本消息
• Markdown 消息
• 图片文件：.png、.jpg、.jpeg、.gif、.bmp、.webp
• 普通文件：.doc、.docx、.pdf、.txt、.xls、.xlsx、.ppt、.pptx、.zip、.rar

同时提供状态检查工具，可查看当前配置是否完整、最近一次记录到的私聊用户是谁、是否已经具备默认发送目标。

目录说明

• server.py：MCP 服务主程序
• config.example.json：配置示例
• config.json：本地实际配置文件，不入库
• tests/test_server.py：测试用例

安装依赖

python -m pip install -r requirements.txt

配置方式

服务启动时会读取 server.py 同目录下的 config.json。

先复制示例配置：

copy config.example.json config.json

然后填写你自己的机器人配置。

如果你还没有 QQ Bot，可以先前往这里申请：https://q.qq.com/qqbot/openclaw/login.html

示例配置如下：

{
  "appid": "your_appid",
  "client_secret": "your_client_secret",
  "token_file": "~/.workbuddy/qq_token.json",
  "openid_store_file": "~/.workbuddy/qq_openid_store.json",
  "api_base_url": "https://api.sgroup.qq.com",
  "token_refresh_url": "https://bots.qq.com/app/getAppAccessToken",
  "gateway_url": "https://api.sgroup.qq.com/gateway"
}

字段说明：

• appid：QQ 机器人 AppID，必填
• client_secret：QQ 机器人密钥，必填
• token_file：访问令牌缓存路径，可选
• openid_store_file：最近私聊用户信息缓存路径，可选
• api_base_url、token_refresh_url、gateway_url：默认已内置，通常不需要改

配置安全说明

• 仓库中只保留 config.example.json
• config.json 已被 .gitignore 忽略，不应提交真实凭据
• token_file、openid_store_file 对应的本地缓存文件也不应提交，建议放在仓库目录之外
• 请只在本地填写真实 appid 和 client_secret

启动服务

python -X utf8 server.py

服务通过标准输入输出处理 MCP 通信。

接入 MCP 客户端

如果你的 MCP 客户端支持通过命令启动本地服务，可以把 qq-bot-sender-mcp 配置为一个标准输入输出型服务。

通用示例：

{
  "mcpServers": {
    "qq-bot-sender": {
      "command": "python",
      "args": ["-X", "utf8", "server.py"],
      "cwd": "D:/AI-BestPractice/mcp/qq-bot-sender-mcp"
    }
  }
}

说明：

• command 需要指向你本机可用的 Python 命令，例如 python 或 Python 绝对路径
• 建议统一加上 -X utf8，避免在 Windows 中文环境下出现标准输入输出或日志编码问题
• cwd 应该指向本仓库目录，这样服务才能读取同目录下的 config.json
• 如果你的客户端不支持 cwd，也可以直接把 args 写成 -X, utf8, D:/AI-BestPractice/mcp/qq-bot-sender-mcp/server.py 的组合

完成接入后，重启 MCP 客户端，让它重新加载工具列表。

MCP 工具

get_status

查看当前配置和默认发送目标状态。

返回信息包括：

• config_path：当前配置文件路径
• appid_masked：脱敏后的 AppID
• token_file：Token 缓存路径
• openid_store_file：最近联系人存储路径
• recent_openid：最近记录到的个人用户 openid
• recent_username：最近记录到的用户名
• last_seen_at：最近记录时间
• can_send：当前是否已经具备默认发送目标

send_text

发送普通文本消息。

参数：

• content：要发送的文本内容，必填
• openid：目标个人用户 openid，选填；不传时使用最近私聊用户

send_markdown

发送 Markdown 消息。

参数：

• content：Markdown 内容，必填
• openid：目标个人用户 openid，选填

说明：自定义 Markdown 发送依赖平台权限，如果平台拒绝会直接返回错误。

send_image

发送图片文件。

参数：

• file_path：图片完整路径，必填
• caption：图片说明文字，选填
• openid：目标个人用户 openid，选填

send_file

发送普通文件。

参数：

• file_path：文件完整路径，必填
• content：文件说明文字，选填
• openid：目标个人用户 openid，选填

推荐使用流程

1. 安装依赖
2. 复制 config.example.json 为 config.json
3. 在 config.json 中填写真实 appid 和 client_secret
4. 启动服务：python -X utf8 server.py
5. 让目标 QQ 用户先给机器人发送一条私聊消息
6. 调用 get_status，确认 can_send 为 true
7. 再调用 send_text、send_markdown、send_image 或 send_file

默认目标是怎么来的

这个服务不再在代码里硬编码某个 openid。

默认发送目标来自最近一次收到的 QQ 私聊事件：

• 当用户先给机器人发送一条私聊消息时
• 服务会自动记录该用户的个人 openid
• 后续如果工具调用里不显式传 openid，就默认发给这个最近联系人

如果你想临时发给别的用户，也可以在工具参数里手动传入 openid。

限制说明

• 仅支持单聊（C2C），不支持群聊
• 图片大小最大 8MB
• 文件大小最大 100MB
• 主动消息发送频率受 QQ 平台规则限制

常见问题

1. 为什么 can_send 是 false？

通常表示当前 openid_store_file 里还没有最近联系人。让目标 QQ 用户先发一条私聊消息，再调用 get_status 检查。

2. 为什么不支持群聊？

当前实现的接口调用、默认目标解析和本地存储都围绕个人用户 openid 设计，没有实现群聊链路。

3. 为什么必须先收到一条私聊？

因为默认发送目标需要从最近一次私聊事件中提取个人 openid。如果你不手动传 openid，服务就必须先知道要发给谁。

4. 什么时候需要手动传 openid？

当你要临时指定目标用户，或者不想使用“最近私聊用户”作为默认发送目标时，可以在发送工具里显式传入 openid。

5. 如果启动时报配置错误怎么办？

优先检查：

• config.json 是否存在
• appid 是否已填写
• client_secret 是否已填写
• 路径字段是否可写

测试

pytest

当前测试覆盖了配置加载、状态查询、默认目标解析等核心逻辑。

发送图片或文件时，请自行准备本地测试文件；仓库内不再附带示例发送素材。