QQ File MCP

在 Codex 中按群名和文件名查找 QQ 群资料，并下载到电脑。

无需让 Agent 逐步识图、点击 QQ 窗口。工具通过本机 NapCat 实时查询资料，再通过 MCP 返回候选文件和搜索范围。

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

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

能做什么

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

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

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

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

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

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

• 只暴露状态、群查询、文件检索和下载工具。

Related MCP server: astral-bridge

快速开始：Windows

需要 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

在本地 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 中。

NapCat 是第三方接入，非腾讯官方开放 API，可能出现掉线、登录验证和账号风控。请阅读 NapCat 安全说明，再决定使用哪个账号。程序没有发消息、删文件或管理群的 MCP 工具，但 NapCat 本身有更广的能力，因此其接口必须保持本机绑定与令牌鉴权。

已有 NapCat / 其他系统

本项目的 Python 工具可连接同一台机器上的 NapCat HTTP 服务。Windows 安装脚本是便捷入口；Linux/macOS 的 QQ 运行环境需自行准备。

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

在 NapCat 中启用 HTTP 服务：127.0.0.1:3000、设置非空 token、messagePostFormat=array。把相同 token 写入 .env。默认不允许连接远程 NapCat 地址。

优先使用 QQ HTTPS 文件链接下载。如果当前 NapCat 不支持链接接口，将尝试 QQ 本地缓存；此时需要通过 QQ_FILE_ALLOWED_ROOTS 指定允许读取的 QQ 缓存目录。不要将整个磁盘或个人主目录加入允许列表。

命令行

# 搜群
./.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 '选定结果的标识'

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

MCP 工具

范围与限制

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

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

• 群文件默认每个目录最多请求 10,000 项、最多查 100 个一级目录；聊天每轮最多 5,000 条。达到上限会在 coverage/warnings 中说明。

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

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

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

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

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

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

开发与验证

./.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

测试覆盖超过 50 个文件、目录检索、群名歧义、历史翻页重复边界、非连续消息 ID、账号切换、结果过期、同名文件、下载路径、链接重定向、令牌隔离，以及真实 stdio MCP 握手。

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

架构与验证边界见 docs/architecture.md。

上游与许可

本项目代码使用 MIT 许可。NapCat 与 QQ 是独立运行依赖，遵循各自的许可和使用规则；仓库不包含其二进制文件。MCP 使用 官方 Python SDK。