OmniQQ-MCP
This MCP server lets an AI agent inspect, deploy, and control NapCatQQ/OneBot 11 QQ accounts and interact with QQ chats.
Check NapCat environment, compare GitHub releases, and deploy/update the runtime with a confirmation gate.
Start, stop, and restart the local NapCat service; log in a new QQ account via QR code; list and hot-switch cached QQ accounts.
Send and delete private/group messages, including CQ codes or message segments, and upload files to friends or groups.
Query current login info, joined group list, recent cached messages, notices, and friend/group requests.
Clear the local recent-message buffer.
Call any NapCat/OneBot 11 action through
call_napcat_apiand list 144+ supported actions for discovery.Use passthrough actions for extra features such as group management, history queries, files/media, OCR, friends, and profile settings.
Integrates with the GitHub Release API to check for the latest NapCat version and automatically download and deploy official release packages for environment setup and updates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OmniQQ-MCP send 'hello' to QQ group 123456"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OmniQQ-MCP: Full-Featured QQ Bot Control & OneBot 11 Model Context Protocol (MCP) Server
OmniQQ-MCP (omniqq-mcp) 是基于 NapNeko/NapCatQQ 与 OneBot 11 协议的 QQ 控制与事件读取 MCP Server。本版本提供 74 项具名工具与 OneBot Action 透传,新增账号隔离缓存、并发请求、只读取消和可靠性修复。
通过本工具,你可以让 Claude Desktop、Google Antigravity、Cursor、Windsurf、Cline、OpenAI Agents 等任意支持 MCP 的 AI 智能体直接获得操控 QQ 的双手与实时感知的眼睛——涵盖私聊/群聊收发、合并转发、群管禁言踢人、群文件上传下载、图片 OCR、好友与资料管理、二维码扫码登录、多 QQ 账号热切换,以及 一键环境自检与自动部署更新。
🔍 核心检索关键词 (Keywords / Topics)
omniqq omniqq-mcp mcp model-context-protocol mcp-server qq-bot napcat napcatqq onebot onebot11 ntqq ai-agent qq-mcp claude-desktop cursor-mcp antigravity chatbot python-mcp
Related MCP server: NapCat MCP Server
✨ 功能特色与核心亮点 (Key Features)
1. 🦾 全量 144+ 项 NapCat 接口 100% 覆盖(14 个核心正交工具 + 74 项具名工具 + 万能透传)
默认暴露 14 个精选正交核心工具 (OMNIQQ_TOOL_PROFILE=core):严格遵循 MCP 最佳实践区间(3~15 个工具),避免撑爆 LLM 上下文窗口,每个工具均附带完整 MCP nnotations、outputSchema、前置权限说明与替代工具路由指引;
74 个具名工具全量兼容 (OMNIQQ_TOOL_PROFILE=full):全部 74 个细分具名工具始终支持通过 ools/call 直接按名调用,或通过设置环境变量 OMNIQQ_TOOL_PROFILE=full 在 ools/list 中全量列出;
万能底层接口透传 (
call_napcat_api):支持直接调用 NapCat 官方引擎全部 144+ 个标准与扩展 Action(如群相册、群打卡、语音转文字fetch_ptt_text、AI 声聊send_group_ai_record等),并内置list_supported_napcat_actions供 AI 自主查阅全部接口目录。
2. 📱 原生支持二维码扫码登录与多 QQ 账号切换
新账号扫码登录 (
login_new_qq_by_qrcode):无需手动折腾配置文件,AI 一键拉起扫码沙箱、在屏幕自动弹出高清二维码图片 (qrcode.png),用户手机扫码后自动生成 OneBot 11 (3000/3001) 端口配置并转为后台常驻服务;多账号免扫码热切换 (
list_qq_accounts/switch_qq_account):自动识别本地已缓存的所有历史登录 QQ 号,支持在多个 QQ 账号之间重启切换上线(耗时取决于登录状态);精准进程控制 (
start_napcat_service/stop_napcat_service/restart_napcat_service):精准管理napcat_runtime下的沙箱进程,按可执行文件与入口路径匹配托管进程。
3. 🛠️ 环境智能自检、版本对比与一键安全自动部署 (Self-Deploying & Auto-Healing)
环境诊断 (
check_napcat_environment):自动检测本地 NapCat 运行时完整性、3000/3001 端口状态,并实时连接 GitHub Release API 对比官方最新版本;带安全确认锁的一键部署与升级 (
deploy_or_update_napcat):内建confirmed=False强制确认门禁,在向用户展示部署路径与版本信息并获得明确授权后,自动下载/解压官方 Release 包并完成初始化;混合自愈启动 (
Auto-Heal):调用任意 QQ 工具时,若检测到后台 NapCat 未启动,自动以最小化无焦点窗口静默拉起服务并完成握手。
4. ⚡ 实时 WebSocket 消息环形缓存 + 机制与策略彻底分离
实时收信感知 (
get_recent_messages/get_recent_notices_and_requests):后台自动维护 WebSocket 长连接与环形消息队列(默认缓存最近 200 条消息与群通知/好友申请),自动净化 CQ 码与富媒体段,支持按群号、QQ 号、关键词秒级检索;机制与策略分离 (
Event Hook扩展总线):MCP Server 保持 100% 纯净通用,不写死任何特定业务白名单;同时在MessageBuffer.register_event_hook(callback)预留事件回调钩子,并支持多路 WebSocket 并行监听,方便开发者后期按需挂载自定义筛选与 Agent 唤醒脚本。
🧰 74 项工具全景矩阵 (Tools Overview)
模块分类 | 工具数量 | 代表性工具列表 |
1. 环境运维、登录与多账号 | 9 |
|
2. 消息收发与社交互动 | 15 |
|
3. 群组管理与治理控制 | 14 |
|
4. 文件与富媒体操作 | 11 |
|
5. 好友关系与账号设置 | 10 |
|
6. 信息与历史记录查询 | 10 |
|
7. 实时消息与通知感知 | 3 |
|
8. 144+ 接口万能透传 | 2 |
|
🚀 快速开始 (Quick Start)
1. 安装依赖
本服务采用原生异步 JSON-RPC 2.0 实现,依赖极度精简:
python -m pip install -r requirements.txt依赖范围见 requirements.txt,WebSocket 使用 websockets>=14,<17。可在本目录构建 wheel 或执行 pip install .,入口为 omniqq-mcp。
本地 NapCat 托管、扫码、进程管理与自动部署仅支持 Windows;连接外部 OneBot URL 时不检查或启动本地端口。Python、WebSocket、MCP 和 NapCat 的版本矩阵,以及升级备份和回滚方式,见 可靠性审查。
2. 在 MCP 客户端中挂载 (mcp_config.json)
在 Antigravity (~/.gemini/config/mcp_config.json)、Claude Desktop 或 Cursor 中添加:
{
"mcpServers": {
"omniqq-mcp": {
"command": "python",
"args": [
"-u",
"/path/to/napcat_mcp/run_mcp.py"
],
"env": {
"PYTHONIOENCODING": "utf-8",
"PYTHONUTF8": "1"
}
}
}
}3. 首次使用自然语言交互示例
挂载完成后,直接对你的 AI 助手说:
“检查一下我的 NapCat 环境状态,如果没部署帮我自动部署一下”
“帮我启动二维码扫码登录一个新 QQ 账号”
“查看我已缓存的 QQ 账号,并切换到另一个账号上线”
“看看我最近收到了哪些 QQ 消息,给群 12345678 发一条通知”
v1.1.0 更新(2026-10-14)
账号隔离缓存:消息、通知和申请按
self_id保存在内存中,切换账号不会混用收件记录。并发与取消:stdio 同时处理请求,慢请求不阻塞查询;只读请求支持
notifications/cancelled,写操作继续完成并报告实际结果。有界事件钩子:事件按序投递,慢同步钩子在线程中执行,队列背压保护 WebSocket 读取。
OneBot 鉴权:HTTP 与 WebSocket 复用用户数据目录中的随机 Token;403 恢复先用只读探测验证候选凭据。
可靠性修复:外部端点不启动本地运行时;账号配置写入失败可见;进程清理匹配目标可执行文件和入口;升级失败回滚备份。
结构化消息与校验:保留原始消息段,补齐历史查询 Action;校验必填项和参数类型,畸形 JSON-RPC 不终止服务。
元数据审计:日志不保留消息正文、文件内容、完整调用参数或凭据,支持轮转和可配置路径。
更新全部 MCP 宿主使用的源码或安装包后,重启 MCP 进程以加载新版本。新安装的运行时、日志、账号选择和 Token 默认位于 %LOCALAPPDATA%\OmniQQ-MCP;已有 napcat_runtime 会继续使用。
v1.2.2 (2026-10-28)
协议与账号边界加固:异常请求不终止 MCP,切账号后旧队列不进入新账号回调,延迟切换保留当前在线账号。
部署与连接恢复:损坏安装仍备份账号数据;解压、复制及健康检查移出事件循环;同进程部署串行化;正常/异常 WS 断开均带退避重连。
凭据隔离:外部 OneBot 地址只使用显式 Token 或通过
OMNIQQ_ONEBOT_TOKEN_FILE明确指定的私有文件,不读取默认本地凭据来探测外部服务。繁忙时响应与缓存修正:工具槽满时 ping 仍可响应,群号过滤与缓存清空行为修正,并新增 19 项离线回归。
v1.2.1 (2026-10-26)
启动前自动清理冲突
QQ.exe进程:每次启动 NapCat 服务前自动检测并结束独立QQ.exe进程,避免同账号互踢与数据库锁冲突。需登录时自动导出二维码至桌面:检测到需要扫码登录时,自动将
qrcode.png复制到桌面(qq_login_qrcode.png)并提示用户打开扫描。纯本地工具入核与未知接口引导:将 6 个无 OneBot HTTP 等价接口的纯本地工具纳入
core模式(共 20 个工具),并为call_napcat_api未知接口报错补充list_supported_napcat_actions指引。
v1.2.0 (2026-10-25)
核心工具精简与全量兼容 (
OMNIQQ_TOOL_PROFILE):默认tools/list暴露 19 个核心与本地工具(14 个高频核心工具 + 5 个无 OneBot 等价接口的纯本地工具),tools/call仍支持直接调用全部 74 项具名工具,设置OMNIQQ_TOOL_PROFILE=full可全量列出。标准注解与返回结构:为全部工具补齐 MCP
annotations与outputSchema,剥离主描述中重复的:param行并补全使用场景、权限要求与副作用说明。
完整历史见 CHANGELOG.md,兼容性和回滚说明见 可靠性说明。
安装与连接
源码根目录运行 python -m pip install .,或安装 Release 附件中的 wheel。安装后可直接使用 omniqq-mcp 命令作为 MCP stdio 入口。
连接已有 OneBot 服务时,设置 NAPCAT_HTTP_URL 和 NAPCAT_WS_URL。本地默认运行时从私有凭据文件读取 Token;外部地址必须通过 OMNIQQ_ONEBOT_TOKEN_FILE 明确指定对应服务的私有 Token 文件(使用 Python 客户端时也可显式传入 token)。请保持该文件与 OneBot 服务端鉴权配置一致,且不要将其放入仓库。
不要上传 Token、账号选择文件、NapCat 登录凭据、二维码、日志或运行时目录。审计仍包含运行时的目标账号和消息 ID,请保存在本地私有目录。
后续计划
继续完善 MCP 客户端兼容性、依赖版本验证、Action 目录与实际 NapCat 版本的对应关系。通用工具与事件钩子的路线图见 docs/ROADMAP.md。
📄 开源协议 (License)
本项目基于 MIT License 开源。
网站版本发布
HaoAn Lab 维护网站展示、版本选择和更新日志,程序无需网站授权或在线版本校验。发布步骤见 网站接入说明。
Available Tools
20 toolscall_napcat_apiADestructive
调用 NapCatQQ 任意 OneBot 11 标准或扩展底层 Action(覆盖全部 144+ 项功能)的通用兜底透传工具。
适用场景:仅当核心专用工具未覆盖所需功能时使用(例如查询历史记录 get_friend_msg_history/get_group_msg_history、群管禁言踢人 set_group_ban/set_group_kick、文件下载与 OCR download_file/ocr_image、好友与资料管理 get_friend_list/set_qq_profile、群相册或打卡等)。不适用与替代:严禁使用本工具替代已暴露的核心专用工具(发送私聊/群聊请用 send_private_msg/send_group_msg,撤回请用 delete_msg,上传文件请用 upload_private_file/upload_group_file);不确定 action 精确名称时,请先调用 list_supported_napcat_actions 检索。
参数约束与交互:action 必须为合法的 OneBot 11 / NapCat 端点名(不含前导斜杠 /);params 为传给该端点的 JSON 键值字典,上传或下载大文件时建议将 timeout 调大至 120.0。
行为、权限与副作用:操作性质完全取决于所调用的 action——get_*/fetch_* 为只读查询,而 delete_*/set_group_kick/set_group_leave 属于不可逆破坏性操作且要求当前账号已在线并具备相应群主/管理员权限;返回标准 OneBot 响应字典 {"status": "ok"|"failed", "retcode": int, "data": ...},未知 action 或参数错误时返回非 0 retcode 并提示调用 list_supported_napcat_actions。
Inputs: action (required), params, timeout. Returns: data, status, message, retcode
check_napcat_environmentARead-onlyIdempotent
检查本地 NapCatQQ 运行时安装状态、OneBot 端口 (3000/3001) 监听情况、本地缓存账号列表,并请求 GitHub Release API 对比官方最新版本。
适用场景:首次连接、排查接口调用失败或判断是否有新版本可升级时优先调用。不适用与替代:若仅需读取当前在线 QQ 的 user_id 与昵称,请改用轻量级的 get_login_info(无需请求 GitHub,速度更快)。
行为与返回:纯只读无副作用操作(包含一次约 5 秒超时的外部 GitHub 版本探测);返回包含 installed、port_listening、cached_accounts、latest_release 及 needs_update 诊断结论的字典,失败时在相应字段返回原因。
Inputs: no named parameters. Returns: data, status, message, retcode
clear_recent_messages_bufferADestructiveIdempotent
清空当前登录账号在本地 MCP 内存环形缓冲区中暂存的所有实时消息、群通知与请求事件记录。
适用场景:在完成一批消息处理或测试重置时,主动清空本地内存缓冲以避免重复读取旧事件。不适用与替代:本工具仅清空本地内存缓存,不会撤回 QQ 聊天消息(撤回请用 delete_msg)也不会清除 QQ 客户端未读红点(标记已读请通过 call_napcat_api 调用 mark_msg_as_read)。
行为与副作用:本地破坏性且不可逆的内存清空操作(不影响 QQ 服务器端历史记录,后续可通过 call_napcat_api 调用 get_friend_msg_history / get_group_msg_history 重新从服务器拉取);返回被清除的记录总数 cleared_count。
Inputs: no named parameters. Returns: data, status, message, retcode
delete_msgADestructive
从私聊或群聊会话中永久撤回指定消息 (OneBot 11: delete_msg)。
适用场景:发错消息需紧急撤回,或作为群主/群管理员撤回群成员的违规发言。不适用与替代:若仅需将群精华消息移出精华列表或删除群共享文件,请通过 call_napcat_api 调用 delete_essence_msg 或 delete_group_file。
参数约束:传入的 message_id 必须来自 send_private_msg、send_group_msg 的返回值或 get_recent_messages 消息记录中的有效整数 ID。
行为与权限限制:不可逆的破坏性操作(撤回后消息无法恢复);撤回自身消息受 QQ 平台 2 分钟时效限制,撤回他人群消息要求当前账号在该群具备管理员或群主权限,超时或权限不足将返回非 0 retcode。
Inputs: message_id (required). Returns: data, status, message, retcode
deploy_or_update_napcatA
自动下载、解压并部署或升级本地 Windows NapCatQQ 运行时环境,同时自动写入 OneBot 11 (3000/3001) 端口配置。
适用场景:当 check_napcat_environment 显示未安装(选 action='deploy')或存在新版本需升级(选 action='update')时使用。不适用与替代:若运行时已安装且仅需启动、重启或切换账号,请改用 switch_qq_account 或 call_napcat_api,切勿重复重装。
参数约束与两阶段门禁:强制采用两阶段确认锁——首次调用必须传 confirmed=False 获取只读预览计划;向用户展示计划并获得明确许可后,再传 confirmed=True 真正执行文件覆写。target_uin 若指定须为 5~11 位纯数字 QQ 号字符串。
行为与副作用:confirmed=True 时会终止现有本地 NapCat 进程并覆写运行时目录(升级失败或健康检查不通过时自动回滚至旧版本备份);仅支持本地 Windows 模式,外部远程 OneBot URL 调用将直接返回 status='failed'。
Inputs: action, confirmed, target_uin, use_local_zip_if_available. Returns: data, status, message, retcode
get_group_listARead-onlyIdempotent
获取当前登录 QQ 账号已加入的全部 QQ 群列表,包含每群的 group_id、group_name、member_count 与 max_member_count (OneBot 11: get_group_list)。
适用场景:在发送群消息或上传群文件前,根据群名称查找对应的 group_id 或遍历已加入的群聊。不适用与替代:若已知具体 group_id 仅需查询该单群的详细资料或需查询好友列表,请通过 call_napcat_api 调用 get_group_info 或 get_friend_list。
参数约束与行为:no_cache=True(默认)会强制向 QQ 服务器拉取最新群列表以确保新加入的群立即可见;纯只读无副作用操作,成功在 data 中返回群信息字典数组。
Inputs: no_cache. Returns: data, status, message, retcode
get_login_infoARead-onlyIdempotent
获取当前在线 QQ 账号的基础身份信息,返回 user_id(QQ 号)与 nickname(昵称)(OneBot 11: get_login_info)。
适用场景:快速确认当前是哪个 QQ 号在线,或验证 OneBot 接口连通性。不适用与替代:若需检查本地所有已缓存的历史账号列表或运行时安装与 GitHub 最新版本对比,请改用 check_napcat_environment。
行为与返回:纯只读无副作用操作;成功返回 status='ok' 及 data: {"user_id": int, "nickname": str},若当前未登录或服务未启动则返回 status='failed' 及非 0 retcode。
Inputs: no named parameters. Returns: data, status, message, retcode
get_login_qrcode_imageARead-onlyIdempotent
读取本地缓存的最新 NapCat 登录二维码图片路径 (qrcode.png),并可选在桌面弹出展示该图片。
适用场景:当 login_new_qq_by_qrcode 已经生成二维码但用户关闭了图片窗口需要重新查看时调用。不适用与替代:本工具不会启动扫码进程或刷新过期二维码;如需发起新的扫码会话,请改用 login_new_qq_by_qrcode。
行为与返回:只读查询本地文件状态(open_image=True 时触发本地图片查看器);文件存在返回 status='ok' 与 qrcode_path,不存在返回 status='not_found'。
Inputs: open_image. Returns: data, status, message, retcode
get_recent_messagesARead-onlyIdempotent
读取 MCP 服务后台通过 WebSocket 实时监听并保存在本地环形内存缓存池(上限 200 条,按登录账号隔离)中的近期 QQ 消息列表。
适用场景:快速轮询或按条件检索服务运行期间实时收到的最新私聊与群聊消息。不适用与替代:若需查询 MCP 启动之前的历史聊天记录或向更早页码翻页,请通过 call_napcat_api 调用 get_friend_msg_history 或 get_group_msg_history;若需查看加群/加好友审批请求或群撤回通知,请调用 get_recent_notices_and_requests。
参数约束与交互:当指定 target_id 时,若 chat_type='group' 则按群号过滤,若 chat_type='private' 则按发送者 QQ 号过滤,若 chat_type='all' 则同时匹配群号或 QQ 号;keyword 对净化后的消息文本 clean_text 与发送者昵称做大小写不敏感子串匹配。
行为与返回:纯内存只读操作(零外部网络延迟,不修改缓存状态);返回 ws_connected、count 及 messages 数组(每项含 message_id, chat_type, user_id, group_id, sender_name, clean_text, time)。
Inputs: count, keyword, chat_type, target_id, +1 more. Returns: data, status, message, retcode
get_recent_notices_and_requestsARead-onlyIdempotent
从本地 WebSocket 环形缓存池中读取近期实时捕获的群通知事件(群文件上传、消息撤回、禁言、成员变动)及加好友/加群验证请求。
适用场景:监听群动态或获取验证请求的 flag 标识以便通过 call_napcat_api 调用 set_friend_add_request / set_group_add_request 审批。不适用与替代:若需读取普通私聊或群聊文字/富媒体消息,请改用 get_recent_messages。
行为与返回:纯本地内存只读操作;返回 ws_connected、notices 数组与 requests 数组。
Inputs: count. Returns: data, status, message, retcode
list_qq_accountsARead-onlyIdempotent
读取本地沙箱中所有已缓存登录凭证的 QQ 账号列表、当前默认激活账号及当前在线账号详情。
适用场景:在切换账号前查询有哪些历史已登录 QQ 号可供免扫码切换。不适用与替代:若仅需确认当前在线账号的 user_id 和昵称,请改用 get_login_info;若需同时检查运行时安装与 GitHub 版本更新,请改用 check_napcat_environment。
行为与返回:纯只读无副作用操作;返回 service_running、online_account、default_account 与 cached_accounts 数组。列表中的账号可直接传给 switch_qq_account 热切换。
Inputs: no named parameters. Returns: data, status, message, retcode
list_supported_napcat_actionsARead-onlyIdempotent
查询 NapCatQQ 引擎支持的全部 144+ 个底层 OneBot 11 与扩展 Action 名称分类目录。
适用场景:在准备调用 call_napcat_api 但不确定目标功能的精确 action 英文名称时,先调用本工具按分类查阅。不适用与替代:若所需操作已有直接对应的核心具名工具(如 send_private_msg、send_group_msg、get_group_list 等),则无需查阅本目录;本工具仅返回接口名称清单,真正执行接口调用请使用 call_napcat_api。
参数约束与交互:category 可按功能域筛选子集(如群管选 'group_management',媒体选 'files_and_media',系统与 AI 声聊选 'ai_and_system'),若传入未识别的分类名则自动回退返回 'all' 全量字典。
行为与返回:纯本地静态目录只读查询(无网络请求、无需登录在线、零副作用);当 category='all' 时返回 total_count 与按分类组织的 categories 字典,指定单一分类时返回 count 与 actions 字符串数组。
Inputs: category. Returns: data, status, message, retcode
login_new_qq_by_qrcodeA
启动全新 QQ 账号的二维码扫码登录流程,生成高清二维码图片 (qrcode.png) 等待手机 QQ 扫码,成功后自动写入 OneBot 11 端口配置并转为后台常驻运行。
适用场景:首次绑定新 QQ 号,或已有账号登录态过期需要重新手机扫码授权时调用。不适用与替代:若目标 QQ 号已在本地缓存列表且凭证有效,请勿重新扫码,应改用 switch_qq_account 免扫码秒级切换。
参数约束与交互:open_image=True 会在本机 Windows 桌面自动弹出二维码查看器;wait_scan_seconds 控制阻塞等待用户手机确认的最大秒数(超时未扫返回 status='scan_timed_out')。
行为与副作用:会主动停止当前正在运行的本地 NapCat 进程并重置自动登录配置;前置要求本地 NapCat 已部署(未部署请先调用 deploy_or_update_napcat),成功时返回 status='logged_in_and_configured'、new_uin 及 online_account。
Inputs: open_image, wait_scan_seconds. Returns: data, status, message, retcode
send_group_msgA
向指定 QQ 群发送单条群聊消息 (OneBot 11: send_group_msg)。
适用场景:在已加入的 QQ 群内发布通知、@成员或发送富媒体消息。不适用与替代:若目标是个人好友私聊,请改用 send_private_msg;若需向群内上传文档或压缩包附件,请改用 upload_group_file。
参数约束与交互:如需产生真实的 @全体成员 或 @指定成员 提醒,必须在 message 中使用 CQ 码 [CQ:at,qq=all] / [CQ:at,qq=123456](且保持 auto_escape=False)或传入 at 类型消息段,手写纯文本“@全体成员”不会触发群提醒。
行为与返回:非幂等群广播操作;前置要求当前 QQ 已加入目标群且未被禁言(@全体成员需群主或管理员权限且受每日次数限制),成功返回 status='ok' 及 data.message_id,无权限或被禁言时返回非 0 retcode。
Inputs: message (required), group_id (required), auto_escape. Returns: data, status, message, retcode
send_private_msgA
向指定 QQ 好友或私聊用户发送单条即时私聊消息 (OneBot 11: send_private_msg)。
适用场景:向个人 QQ 账号发送文本、CQ 码或富媒体消息段。不适用与替代:若目标是 QQ 群聊,请改用 send_group_msg;若需发送本地文件附件,请改用 upload_private_file。
参数约束与交互:message 支持含 CQ 码的字符串或 OneBot 标准消息段数组(如 [{"type":"face","data":{"id":"14"}}]);仅当希望将 [CQ:...] 原样作为纯文本输出时才将 auto_escape 设为 True。
行为与返回:非幂等外部发送操作(调用即真实发出消息);前置要求当前账号已在线且与目标存在好友或临时会话关系,成功返回 status='ok' 及 data.message_id(可用于后续 delete_msg 撤回),被风控或非好友时返回非 0 retcode。
Inputs: message (required), user_id (required), auto_escape. Returns: data, status, message, retcode
start_napcat_serviceAIdempotent
启动本地 NapCatQQ 后台服务进程并等待 OneBot (3000/3001) 端口就绪,同时挂载后台 WebSocket 事件监听。
适用场景:当本地服务处于停止状态、需要以默认或指定已缓存账号拉起后台进程时调用(启动前会自动检查并结束冲突的独立 QQ.exe 进程;若检测到需要扫码登录,会自动把登录二维码放到桌面并提示用户打开扫描)。不适用与替代:若服务已在运行且需切换其他已缓存账号,请改用 switch_qq_account。
行为与返回:幂等操作——启动前先结束冲突的独立 QQ.exe 进程;若端口已在监听则返回 status='already_running';新启动成功返回 status='started';若需扫码登录则将二维码导出至桌面并返回 login_required=True 及 desktop_qrcode_path。
Inputs: uin, wait_seconds. Returns: data, status, message, retcode
stop_napcat_serviceADestructiveIdempotent
安全终止本地后台运行的 NapCatQQ 沙箱进程(严格校验进程可执行文件与入口路径,绝不误杀系统其他 Node.js 进程)。
适用场景:需要彻底下线当前 QQ 机器人、释放本地 3000/3001 端口或维护运行时目录时调用。不适用与替代:若希望重启服务或切换其他已缓存 QQ 号上线,请直接改用 switch_qq_account。
行为与副作用:破坏性但幂等的进程终止操作——调用后当前 QQ 账号立即离线且实时消息监听中断,直至重新调用 switch_qq_account、login_new_qq_by_qrcode 或任意触发自动自愈的核心工具;返回被终止的 PID 列表 stopped_processes 与端口状态。
Inputs: no named parameters. Returns: data, status, message, retcode
switch_qq_accountAIdempotent
在本地已保存登录凭证的多个 QQ 账号之间免扫码热切换,自动更新默认账号、OneBot 端口配置及按账号隔离的消息缓存池。
适用场景:目标 QQ 号此前已在本地扫码登录过(可通过 check_napcat_environment 的 cached_accounts 查看),需快速切换上线时调用。不适用与替代:若目标是一个从未登录过的新 QQ 号或登录凭证已失效,请勿使用本工具,应改用 login_new_qq_by_qrcode 扫码登录。
参数约束与交互:uin 必须为 5~11 位纯数字字符串;当 restart_immediately=True 时会立即终止旧账号进程并等待最多 wait_seconds 秒直至新账号端口就绪,为 False 时仅修改配置待下次启动生效。
行为与返回:幂等配置变更与进程重启操作(仅限本地运行时,外部 URL 返回失败);返回 status、switched_to、online_account 与 available_accounts。
Inputs: uin (required), wait_seconds, restart_immediately. Returns: data, status, message, retcode
upload_group_fileA
将本机磁盘上的文件上传至指定 QQ 群的群文件共享空间 (NapCat OneBot 11: upload_group_file)。
适用场景:向 QQ 群发布共享资料、汇总表或通知附件。不适用与替代:若需将文件单独私发给某个好友,请改用 upload_private_file;若仅需在群内发送文字通知,请改用 send_group_msg。
参数约束与交互:file_path 必须为本机已存在的绝对路径;省略 folder 时默认上传至群文件根目录,若指定 folder 则须传入通过 call_napcat_api(action='get_group_root_files') 查询到的有效群文件夹 ID。
行为与返回:非幂等群文件创建操作(默认超时 120 秒,同名文件通常会在群文件列表中产生新条目);前置要求当前账号已加入目标群且群文件空间未满、具备上传权限,成功返回 status='ok'。
Inputs: group_id (required), file_name (required), file_path (required), folder. Returns: data, status, message, retcode
upload_private_fileA
将本机磁盘上的文件作为私聊附件发送给指定 QQ 好友 (NapCat OneBot 11: upload_private_file)。
适用场景:向个人 QQ 好友交付文档、表格、PDF 或压缩包等本地文件。不适用与替代:若需将文件上传至 QQ 群共享空间,请改用 upload_group_file;若仅需发送纯文本或图片消息段,请改用 send_private_msg。
参数约束与交互:file_path 必须为当前机器上已存在且可读的本地绝对路径(如 D:/Desktop/report.xlsx);file_name 应包含正确的文件扩展名以便接收方客户端识别打开。
行为与返回:非幂等外部文件传输操作(默认超时 120 秒以支持大文件上传);前置要求当前账号已在线且目标为好友,成功返回 status='ok',若本地文件不存在、超出大小限制或非好友则返回非 0 retcode。
Inputs: user_id (required), file_name (required), file_path (required). Returns: data, status, message, retcode
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Every description carries an explicit "not applicable, use X instead" clause, so an agent can reliably choose among superficially similar tools like get_login_info vs list_qq_accounts vs check_napcat_environment, or send_private_msg vs upload_private_file. The remaining overlap sits in the runtime-lifecycle cluster (start_napcat_service, switch_qq_account, login_new_qq_by_qrcode, deploy_or_update_napcat), which all stop/restart the same process and only the prose keeps them apart. call_napcat_api also overlaps everything by design, though its description fences it off as a fallback.
All 20 names are lowercase snake_case with a verb-first shape (check_/deploy_/list_/switch_/login_/get_/start_/stop_/send_/delete_/upload_/clear_/call_), and the paired tools mirror each other cleanly (send_private_msg/send_group_msg, upload_private_file/upload_group_file). Deviations like deploy_or_update_napcat and call_napcat_api are still verb-first and immediately readable.
Twenty tools is slightly above the comfortable band, but the domain genuinely spans four areas: runtime install/lifecycle, account switching and QR login, messaging, and file upload. Each tool maps to a distinct step, and the deliberate use of call_napcat_api plus list_supported_napcat_actions keeps the dedicated surface from ballooning to 144+. A couple of lifecycle tools (start vs switch vs login) could arguably be merged.
Core workflows — install/update, start/stop, QR login, account switch, send/recall messages, upload files, read recent traffic — are fully covered end to end, and the read side has a clear 200-message cache plus history fallback. However, notable operations such as group management (kick/ban/mute), friend and group info lookups, friend/group request approval, and history paging have no dedicated tool and require knowing exact action names for call_napcat_api. This is workable but adds a discovery step.
Maintenance
Related MCP Connectors
Command your AI agents by voice: PTT rooms, channels, direct messages, agent email, memory (mRAG).
Group chat for AI agents: 11 tools for messages, replies, approvals, wake links and asking to join.
Voice and chat for AI agents — Discord, Teams, Meet, Slack, Zoom, Telegram, WhatsApp, NC Talk, SIP
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables AI clients to send and receive QQ messages through NapCatQQ (OneBot v11) for both private and group chats. It supports message context management, real-time WebSocket listening, and human-like typing simulation.726MIT
- FlicenseCqualityDmaintenanceEnables interaction with NapCat QQ bot APIs for group management, messaging, and system operations. Supports HTTP and WebSocket modes with security features like group restrictions and readonly mode.574-
- FlicenseAqualityBmaintenanceEnables 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-
- AlicenseAqualityCmaintenanceExposes NapCat/OneBot v11 QQ-bot APIs as MCP tools for any MCP client, and includes an LLM-driven QQ bot with memory, knowledge base, tool calling, web search, multimodal recognition, and permission controls.45MIT