QQ File MCP

在 Codex 中查找 QQ 群资料、读取原生群作业和聊天补充要求，并预览自己的提交。

无需让 Agent 逐步识图、点击 QQ 窗口。工具通过本机 OneBot 接口实时查询资料，再通过 MCP 返回候选文件和搜索范围。Windows 可使用 SnowLuma 加载到正在运行的桌面 QQ，在同一账号下聊天、查群文件和下载。

你：找「示例学习群」里文件名包含「课件」的文件。
Codex → qq_search_files → 群文件目录 + 可获取的聊天附件
你：下载第二个。
Codex → qq_download_file → 本机路径、文件大小、SHA-256
你：总结刚下载的课件。
Codex → qq_read_downloaded_file → 分页正文 → 总结并标明页码

这是单用户、自行部署的项目。QQ、桥接工具、MCP 工具和 Codex 运行在同一台电脑；电脑关闭时服务离线。无需租服务器，也不调用额外的模型 API。Codex 自身的账号与使用额度照常适用。

需要同时聊天和查文件时，使用桌面会话接入方式。 原有 NapCat Shell 安装仍可使用，但它独立登录 QQ，同账号与桌面 QQ 可能发生登录冲突；两种方式不要一起启动。

能做什么

• 用群名、群名关键词或群号定位已加入的群；同名群先供选择。

• 实时查询根目录及接口返回的一级文件夹，不预同步。

• 文件名支持完整名称、部分名称、大小写与全半角归一化；明确要求全部文件时可传 *。

• 不知道文件名时，可按群名和发布人查找；支持 QQ 号、昵称/群名片及发布时间范围，同名成员先供选择。

• 聊天附件默认扫描最近 1,000 条可获取消息，可分段继续向前查询。

• 返回实际扫描条数、时间范围、截断或错误原因，避免将“未扫描到”当成“不存在”。

• 下载前重新确认文件，保留同名文件，返回 SHA-256；不会执行下载内容。

• 离线查找已下载的文件，直接读取 PDF、DOCX 正文和表格、TXT、Markdown、CSV 等文本；无需重新下载。

• 下载时保存群、上传者/发送者、发布时间和来源记录；之后可离线按这些信息筛选。

• 按页或行返回文字及续读位置，长页截断后仍可接着读。

• 检索聊天正文及作业补充说明，返回发送者、时间和原文依据；长消息可以续读。

• 准备自己的文字或文件提交预览；发送默认关闭，启用后仍需明确授权准确目标和内容。

• 不提供删除或群管理工具；QQ 原生“群作业”页面暂未支持。

Related MCP server: qq-onebot-mcp

快速开始：Windows 桌面 QQ 共享会话

需要 Python 3.11+、官方 QQNT、Codex。保留电脑 QQ 的正常登录。

git clone https://github.com/HJLiyu/qq-file-mcp.git
cd qq-file-mcp
./scripts/setup.ps1
Copy-Item .env.example .env

按 桌面 QQ 接入说明 手动准备官方 SnowLuma 发行包，启动控制台并加载已有 QQ 进程。核对 OneBot HTTP 服务绑定 127.0.0.1、令牌非空、消息格式 array，关闭桥接的自动状态回复命令。在 .env 中填写：

QQ_FILE_BACKEND=snowluma
ONEBOT_URL=http://127.0.0.1:3000
ONEBOT_TOKEN=你的本地OneBot访问令牌

检查连接并注册工具：

./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env doctor
./scripts/register-codex.ps1

重新加载 Codex 的 MCP 连接或开启新对话，让 Codex 调用 qq_status、qq_search_files。电脑 QQ 继续聊天，工具复用这个登录会话。退出 QQ 或桥接工具后，实时检索暂不可用。

聊天历史限制： SnowLuma v1.14.20 的原版接口需要已观察到该群的消息，才能从这个起点向前取历史；首次加载后安静的群可能返回空。打开群窗口不保证能补齐起点。本工具返回 HISTORY_ANCHOR_UNAVAILABLE 和实际覆盖范围；群文件目录不受此限制。本仓库没有提供修改版桥接程序，详见接入说明。

原有方式：Windows NapCat Shell

需要 Python 3.11+、已安装的官方 QQNT、Codex，以及可以访问目标群的 QQ 账号。

git clone https://github.com/HJLiyu/qq-file-mcp.git
cd qq-file-mcp
./scripts/setup.ps1 -WithNapCat
./scripts/start-napcat.ps1 -OpenWebUI

先关闭桌面 QQ，再在本地 NapCat 页面完成 QQ 登录。安装脚本将：

1. 创建 .venv，安装本项目依赖。

2. 从 NapCat 项目发布页下载固定版本 v4.18.28，核对 SHA-256 后解压到 .local/。

3. 从已安装 QQ 的运行目录复制该发布包缺少的 crypto.dll、ssl.dll。不修改 QQ 安装文件。

4. 生成本地令牌、.env 和仅绑定 127.0.0.1 的配置。

QQ 安装在其他位置时：

./scripts/setup.ps1 -WithNapCat -QQInstallDirectory 'D:\Apps\QQNT'

检查连接、接入 Codex：

./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env doctor
./scripts/register-codex.ps1

重新加载 Codex 的 MCP 连接或开启新对话。让 Codex 调用 qq_status，再要求它搜索群文件。注册命令中只有配置文件路径，访问令牌保留在本机 .env 中。

查完后返回日常电脑 QQ：

./scripts/stop-napcat.ps1
# 然后自行打开桌面 QQ 并登录。

停止脚本只终止本项目 .local/napcat-node/node.exe 对应的进程，保留 QQ 登录数据和已下载的文件。停止期间 MCP 的实时检索与下载不可用，下次需要时再次关闭桌面 QQ、运行 start-napcat.ps1 -OpenWebUI 并登录。

NapCat 是第三方接入，非腾讯官方开放 API，可能出现掉线、登录验证和账号风控。请阅读 NapCat 安全说明，再决定使用哪个账号。发送自己的作业需要单独启用，删除和群管理不开放；桥接本身有更广的能力，因此其接口必须保持本机绑定与令牌鉴权。

已有 OneBot 服务 / 其他系统

本项目支持同一台机器上的 NapCat 或 SnowLuma HTTP 服务。Windows 安装脚本只提供 Python 工具和可选 NapCat Shell 环境；其他系统的 QQ 运行环境需自行准备。

python -m venv .venv
# 激活对应系统的虚拟环境后：
python -m pip install -e .
cp .env.example .env

启用 HTTP 服务：127.0.0.1:3000、设置非空 token、消息格式 array（NapCat 名称为 messagePostFormat，SnowLuma 为 messageFormat）。把相同 token 写入 .env 的 ONEBOT_TOKEN，并设置 QQ_FILE_BACKEND=napcat 或 snowluma。连接地址只允许本机回环。

旧配置中的 NAPCAT_URL / NAPCAT_TOKEN 仍有效；没有设置后端时默认 napcat。新的 ONEBOT_* 配置优先。文件和分页引用绑定接入方式，切换后会拒绝旧引用并要求重新搜索；推荐使用独立 QQ_FILE_STATE_DIR。

优先使用 QQ HTTPS 文件链接下载。如果当前 NapCat 不支持链接接口，将尝试 QQ 本地缓存；此时需要通过 QQ_FILE_ALLOWED_ROOTS 指定允许读取的 QQ 缓存目录。不要将整个磁盘或个人主目录加入允许列表。SnowLuma 的 get_file 只适用于图片/语音缓存，群文件下载链接不可用时会报错，不会尝试该后备路径。

命令行

# 搜群
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env groups '示例学习群'

# 搜群文件与最近可获取的聊天附件
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env search '示例学习群' '课件'

# 列出群文件（此命令不自动批量下载）
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env search '示例学习群' '*' --source group_files

# 继续向前搜索聊天附件，保持同一群和关键词
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env search '示例学习群' '课件' --history-cursor '上次返回的标识'

# 下载选定文件；使用搜索返回的 result_id
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env download '选定结果的标识'

# 不知道文件名，只知道群名和发布人
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env search '示例学习群' --publisher '张老师' --source group_files

# 离线从已下载文件中按群和发布人找资料
./.venv/Scripts/python.exe -m qq_file_mcp --env-file .env downloads --group '示例学习群' --publisher '张老师'

默认下载目录：~/Downloads/QQ-File-MCP。可用 .env 中的 QQ_FILE_DOWNLOAD_DIR 修改。

让 Agent 使用已下载文件

更新代码和依赖后，重新加载 Codex 的 MCP 连接；若当前对话仍显示旧工具列表，开启新对话或重启 Codex。QQ 和桥接工具无需为离线读取重新登录。

直接说“总结已经下载的课件”或“在已下载的笔记里找数值积分的说明”。Agent 先用 qq_list_downloaded_files 定位文件，再用 qq_read_downloaded_file 获取正文。下载工具新增 local_file_id，可以立即传给读取工具。旧版下载的文件也可直接列出，包括专用下载目录内的普通子目录。

读取结果带页号、行号或 DOCX 正文块编号、SHA-256 和 next_read。只返回指定范围，不会把整个长文档一次塞进上下文。DOCX 不提供页码，图片、公式、页眉页脚等未解析；扫描 PDF 暂无 OCR，公式和表格的提取可能不完整。详见 离线读取说明。

v0.8.0 增加 DOCX 离线读取，修复状态数据库连接未及时关闭、Windows 文件被占用的问题；提交文件读取或暂存失败时返回 SUBMISSION_IO，便于 Agent 提示检查文件占用、权限或磁盘空间。已有工具名称和参数兼容，升级后重新加载 Codex 的 MCP 连接即可。

例如“找示例学习群里张老师9月份发的资料”：Agent 可以组合 group、publisher、published_after、published_before 和可选的文件名。新下载会持久保存实际观察到的群、发布人和发布时间；旧文件缺少这些记录时标为未知，有来源筛选时不会猜测匹配。群文件的发布人是上传者，聊天附件是发送者，不代表文档作者。

MCP 工具

例如“结合老师发的文件和之后的聊天补充，整理作业要求”。Agent 使用文件工具和聊天工具取证，并注明发送者、时间和实际查到的范围。提交先展示群名/群号及准确文字或文件；默认 QQ_FILE_ENABLE_SUBMISSIONS=false，文件只可来自独立的 submission_dir。启用发送、生成预览均不代表批准提交。配置、用法与回执含义见 作业与提交说明。

v0.7.0 可直接说“读取这个群的原生群作业，查看我是否提交过”，或“把提交目录里的答案 PDF 准备成这份原生作业的预览”。原生工具复用 SnowLuma 桌面会话，支持文字和一个 PDF/DOC/DOCX 文件，可附文字；文件上传使用原生作业专用接口。已有答案默认禁止覆盖。真实原生读取、图片/历史PDF下载和本机预览已验证；原生文件提交为试验功能，真实上传与提交尚未验收，不能将模拟测试当成真实成功。详见 原生群作业说明。更新后重载 Codex 的 MCP 连接，加载新增的 file_path 参数；仍是17个工具，无需重登QQ。

范围与限制

• 同账号聊天与群文件工具已在 Windows QQNT + SnowLuma v1.14.20 中验证。上游版本、QQ 版本和登录状态改变后仍需重新验证；独立 NapCat Shell 不属于共享会话方式。

• 作业汇总可以结合原生要求、文件及可获取聊天正文。关键词查询可能漏掉不含该词的补充说明；图片/语音/转发不自动提取正文。群消息/文件回执不代表原生作业提交；原生答案只有准确读回后才报告已验证，均不代表老师认可。

• 聊天历史仅覆盖当前 QQ 会话实际能取回的内容，无法保证任意年份的消息都可用。

• 合并转发中的文件、在线文件和多层嵌套目录尚未支持；普通聊天 file 附件已实现。

• 群文件默认每个目录最多处理 10,000 项、最多查 100 个一级目录；聊天每轮最多 5,000 条。即使上游忽略请求数量，也在客户端限制目录处理。达到上限会在 coverage/warnings 中说明。

• 两种来源独立限时，默认每种最多 40 秒；一个来源失败不会丢弃另一来源的结果。

• 超时或到达范围上限后，以返回的范围为准。空结果不等于完整历史中不存在。

• 文件结果及继续查询标识默认保留一小时。QQ 会话重启后，聊天消息标识可能失效，需要重新搜索。

• 已下载文件的来源记录持久保存在本机状态库；不受结果引用的一小时有效期影响。昵称/群名片是查询或下载时观察到的名字，离线时不自动跟随改名；QQ 号可精确定位。

• 同一文件可能分别出现在群目录和聊天附件中，本版保留来源，不通过名称猜测它们是同一文件。

• 默认单文件大小上限 512 MiB；过期文件、权限不足或内容大小变化会明确报错。

• 离线读取默认单文件最多 50 MiB、单次解析 20 秒，最多10页或500行/正文块、20,000字符。DOCX 正文 XML 展开后最多8 MiB；暂不支持加密文档、旧版 DOC、Excel、通用压缩包和图片 OCR。

• 提交文字或单文件的预览有效15分钟，默认文件上限50 MiB。超时或发送中断可能已经发送，同一预览不能自动重试，需先在QQ核对。

• 原生 QQ 下载在某些运行环境中可能超时；本版优先使用受限 QQ HTTPS 下载，NapCat 的原生缓存作为后备路径。

开发与验证

./.venv/Scripts/python.exe -m pip install -e '.[dev]'
./.venv/Scripts/python.exe -m pytest -q
./.venv/Scripts/python.exe -m ruff check src tests scripts
./.venv/Scripts/python.exe -m build

测试覆盖两种后端的历史参数差异、同秒消息排序、目录检索、群名歧义、历史翻页、账号切换、同名文件、下载路径、链接重定向、令牌隔离，以及真实 stdio MCP 握手。离线读取另覆盖中文编码、PDF 页码、DOCX 段落/表格顺序与修订警告、长正文续读、压缩/XML 解析上限、文件变化与过期、Windows junction/符号链接边界和解析子进程超时终止。状态库测试核对事务提交、回滚和连接释放；提交文件测试覆盖读取失败及部分暂存清理。

测试和示例不包含真实 QQ 消息。.env、.local/、会话配置、检索结果与下载文件均不应提交到 Git。

架构与验证边界见 docs/architecture.md，本轮改进与后续验收目标见 扩展方向。

上游与许可

本项目独立编写的客户端代码使用 MIT 许可。QQ、NapCat、SnowLuma 是独立运行依赖，遵循各自的许可和使用规则；仓库不包含其源代码、修改版或二进制文件。SnowLuma 使用源码可见非商业许可，还需阅读其 EULA。MCP 使用 官方 Python SDK。