Skip to main content
Glama

qq-mcp

简体中文 | English

让 AI 用你自己的 QQ 号做事的 MCP 服务器:读消息、发消息、管群、操作 QQ 空间。260 个工具,一个 Docker 容器,能直接部署到云上(Streamable HTTP),掉线会自动重新登录。

⚠️ 用自动化程序操作个人 QQ 违反腾讯用户协议,账号可能被限制。风险自负,请只用于自己的账号。

能做什么

类别

工具举例

聊天

find_contact 按名字找人/群 · read_chat · search_chat · send_text(支持 @、引用、表情) · send_image / send_voice / send_video / send_file · reply_to_message · forward_messages 合并转发 · poke · view_image(让 AI 看图)

实时

get_unread · list_recent_chats · wait_for_message · get_events(撤回、入群、好友申请…)

群

成员列表、禁言、踢人、管理员、群名片、头衔、群公告、群文件、群相册、精华、群待办、加群申请…

QQ 空间

发说说(带图、可见范围)、删说说、点赞、评论/回复、转发、好友动态、访客、留言板(读/写/回复/删)、相册与照片、点赞名单、浏览/点赞数、亲密度

兜底

onebot_call 调任意 OneBot 动作 · qzone_request 带登录态调任意 QQ 空间接口

node dist/index.js tools 列出全部工具;QQ_TOOLSETS / QQ_READ_ONLY 可以只开放一部分。

Related MCP server: OmniQQ-MCP

原理

容器里跑一个官方原版 Linux QQ(虚拟显示器上),SnowLuma 把它变成 OneBot v11 接口,本项目再把每个动作变成 MCP 工具,并加上聊天便捷工具、QQ 空间扩展、扫码登录和登录守护。

几个现成方案没有解决的点:

  • 不需要任何特权:SnowLuma 用 ptrace 注入 QQ,而大多数云平台(ptrace_scope=1)只允许追踪子进程。这里由 SnowLuma 的运行时进程亲自拉起 QQ(docker/qq-launcher.mjs),所以在 Railway 这类平台上也能注入。

  • 扫码登录走 MCP 或网页:qq_login 返回登录窗口截图;/login/<token> 是一个实时刷新的二维码页面。

  • 登录守护:每 30 秒检查一次——记住的账号自动点「登录」、自动关掉下线弹窗、接口卡死就重启 QQ;只有真的需要扫码时才通过 NOTIFY_WEBHOOK 通知你。

部署

Docker

docker build -t qq-mcp .
docker run -d --name qq-mcp --shm-size=1g \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
  -v qq-data:/data -p 8000:8000 qq-mcp

MCP 地址(Streamable HTTP):http://<host>:8000/mcp/<MCP_AUTH_TOKEN>,或 /mcp 加 Authorization: Bearer <token>。 打开 http://<host>:8000/login/<MCP_AUTH_TOKEN>,用手机 QQ 扫码。登录状态保存在 /data,重启后自动登录。

Railway

从你自己的仓库副本部署(Dockerfile),挂一个卷到 /data,设置 MCP_AUTH_TOKEN(至少 24 位随机字符),生成域名即可。railway.json 已配置健康检查。

  • 一个 QQ 客户端约占 1GB 内存。

  • 请从私有 fork 部署:Railway 的 GitHub 集成会把部署记录和提交状态(项目/服务 ID、控制台链接)写回所连接的仓库。

QQ 客户端来源

腾讯的下载服务器拒绝大多数境外 IP,所以默认从公开镜像 linyuchen/pmhq 里复制未修改的 /opt/QQ(QQ 3.2.34)。在国内构建可以直接用官方安装包:

docker build --build-arg QQ_DEB_URL=<https://im.qq.com/linuxqq/ 上的 .deb 链接> -t qq-mcp .

配置(环境变量)

变量

说明

MCP_AUTH_TOKEN

必填,访问令牌

NOTIFY_WEBHOOK

需要扫码时发通知:Discord webhook、含 {text} 的 URL(Bark、Server酱…),或任意接受 JSON POST 的地址

PUBLIC_URL

通知里登录链接的域名(Railway 上自动识别)

QQ_WATCHDOG_INTERVAL

登录检查间隔秒数,默认 30;QQ_WATCHDOG=off 关闭

QQ_TOOLSETS

只开放这些类别,如 chat,events,message,qzone,qzone_web

QQ_READ_ONLY

1 = 只开放只读工具

QQ_DISABLED_TOOLS

逗号分隔的要隐藏的工具名

ONEBOT_WS_URL / ONEBOT_ACCESS_TOKEN

改连其他 OneBot v11 实现(NapCat、LLBot…),不用自带的

开发

npm install
npm test        # 离线端到端测试(假 OneBot 服务 + 真实 MCP HTTP)
node dist/index.js            # stdio 模式
MCP_AUTH_TOKEN=... node dist/index.js serve   # HTTP 模式

许可

本项目代码采用 MIT 许可。它依赖的 SnowLuma(运行时,以及提供动作目录的 npm 包 @snowluma/mcp)采用源码可见、非商业许可,构建时从官方渠道下载,不包含在本仓库中;商业使用请先取得 SnowLuma 作者授权。QQ 是腾讯的软件。本项目与腾讯、SnowLuma 均无关联。

Available Tools

260 tools
add_custom_faceB

添加收藏表情 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。

Inputs: file (required).

add_group_tagC

向某个群分类添加资料标签 替换实际群分类和标签;需要当前账号有管理权限。

Inputs: name (required), group_class (required).

cancel_group_album_media_likeC
Destructive

cancel_group_album_media_like album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。 batch_id 必须是实际批次的十进制字符串。

Inputs: album_id (required), batch_id (required), group_id (required), lloc.

cancel_group_todoA
Destructive

取消群待办 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 必须是该群的消息。

Inputs: group_id (required), message_id (required).

can_send_imageC
Read-only

can_send_image Returns: 能力查询结果。

Inputs: no named parameters.

can_send_recordC
Read-only

can_send_record Returns: 能力查询结果。

Inputs: no named parameters.

clean_cacheA
Destructive

清理缓存 兼容占位接口,当前返回成功但不执行清理。流式临时文件清理请使用 clean_stream_temp_file。

Inputs: no named parameters.

clean_stream_temp_fileA
Destructive

清理流式传输临时文件(仅清理 stream 上传/下载目录) 清理未使用的流式临时文件;不会清理正在传输的项目。 Returns: { message, removed }

Inputs: no named parameters.

click_inline_keyboard_buttonA

点击内联键盘按钮 参数必须来自同一条机器人按钮消息;msg_seq 是消息序号,不是 message_id。

Inputs: msg_seq (required), group_id (required), bot_appid (required), button_id (required), +1 more.

comment_qzoneA

评论说说或回复指定评论(普通评论支持带图,楼中楼仅支持文字) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。 Rules: all or none of: comment_id, comment_uin; all or none of: reply_uin, reply_name; reply_uin/reply_name require comment_id/comment_uin; images are not supported for comment replies; comment_id, reply_name and reply content must not be blank; comment_uin and reply_uin must be safe integers.

Inputs: tid (required), content (required), images, reply_uin, +4 more.

comment_qzone_public_feedA

评论推荐动态,支持文本或上游富文本条目 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 Returns: 上游评论结果,包含新评论,保留未知字段。

Inputs: feed (required), content (required).

complete_group_todoA

完成群待办 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 必须是该群的消息。

Inputs: group_id (required), message_id (required).

create_flash_taskB

创建闪传任务 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。 files 不能为空。

Inputs: name, files, thumb_path.

create_group_file_folderC

创建群文件夹 将 group_id 替换为当前账号可访问的群号。 Returns: { result: { retCode, retMsg }, groupItem: { folderInfo: { folderId, folderName, folderPath, createTime, modifyTime, createUin, modifyUin } } }

Inputs: name (required), group_id (required), parent_id.

delete_custom_faceA
Destructive

删除收藏表情 emoji_id 来自 fetch_custom_face_detail。

Inputs: emoji_id (required).

delete_essence_msgA
Destructive

移除精华消息 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required).

delete_flash_fileB
Destructive

删除闪传文件 fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。

Inputs: fileset_id (required).

delete_friendB
Destructive

删除好友 会删除指定好友;仅在明确需要删除时调用。

Inputs: user_id (required), block.

delete_group_fileB
Destructive

删除群文件 替换群文件列表中的实际 file_id;需要对应文件操作权限。

Inputs: file_id (required), group_id (required).

delete_group_file_folderC
Destructive

删除群文件夹 会删除指定群文件夹,确认资源后调用。

Inputs: group_id (required), folder_id (required).

delete_group_folderC
Destructive

删除群文件夹 会删除指定群文件夹,确认资源后调用。

Inputs: group_id (required), folder_id (required).

delete_group_tagB
Destructive

从某个群分类移除资料标签 替换实际群分类和标签;需要当前账号有管理权限。

Inputs: name (required), group_class (required).

delete_msgA
Destructive

撤回消息 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required).

delete_qzone_msgA
Destructive

删除一条说说(QQ 空间,按 tid) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。

Inputs: tid (required).

delete_qzone_public_commentA
Destructive

删除推荐动态的一条评论(需有权限) feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 comment 可取 get_qzone_public_feed_detail 返回的 feed.feed.cell_comment.comments,或后续评论页;保留完整对象。 Returns: 上游删除结果,保留未知字段。

Inputs: feed (required), comment (required).

delete_qzone_public_replyA
Destructive

删除推荐动态评论下的一条回复(需有权限) feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 comment 可取 get_qzone_public_feed_detail 返回的 feed.feed.cell_comment.comments,或后续评论页;保留完整对象。 reply 使用该评论下的完整回复对象。 Returns: 上游删除结果,保留未知字段。

Inputs: feed (required), reply (required), comment (required).

del_group_album_mediaA
Destructive

删除群相册图片或视频 album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。

Inputs: lloc (required), album_id (required), group_id (required).

del_group_noticeA
Destructive

删除群公告(fid 或 notice_id 二选一) notice_id 来自 _get_group_notice;删除需要管理权限。

Inputs: group_id (required), fid, notice_id.

do_group_album_commentC

do_group_album_comment album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。

Inputs: lloc (required), content (required), album_id (required), group_id (required).

download_fileA

下载文件(url 或 base64)到 data/downloads 保存到 SnowLuma 服务端临时目录,返回服务端路径;不是 MCP 主机下载路径。 Returns: { file }

Inputs: url, name, base64, headers.

download_file_image_streamA

以流式方式下载图片(缓存图片 id / URL / stream 目录本地文件) file_id 来自当前账号图片消息;经 invoke_action 调用。 Returns: 流式帧:file_info → file_chunk* → file_complete

Inputs: file, file_id, chunk_size.

download_file_record_streamA

以流式方式下载语音(缓存语音 id / URL / stream 目录本地文件) file_id 来自当前账号语音消息;经 invoke_action 调用。 Returns: 流式帧:file_info → file_chunk* → file_complete

Inputs: file, file_id, chunk_size.

download_filesetA

解析闪传文件下载直链(不下载,由调用方实现下载) fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。 file_index 从 0 开始。 Returns: { url, file_name, file_size }

Inputs: fileset_id (required), file_name, file_index.

download_file_streamA

以流式方式下载文件(stream 目录本地文件 / URL / 缓存媒体) 替换实际公开可访问地址;经 invoke_action 调用,文件保存到 MCP 下载目录。 Returns: 流式帧:file_info → file_chunk* → file_complete

Inputs: file, file_id, chunk_size.

download_mediaA
Read-only

Save the image/voice/video/file of a message (or any URL) on the server and return its local path, which other tools (send_file, send_qzone_msg images…) accept.

Inputs: url, name, index, message_id.

fetch_custom_faceB
Read-only

获取自定义表情 Returns: 字符串数组:return_type=url 时为图片 URL,return_type=id 时为 emoji_id。

Inputs: count, return_type.

fetch_custom_face_detailB
Read-only

获取自定义表情详情 Returns: 自定义表情详情数组,包含资源标识、图片地址、摘要与描述。

Inputs: count.

fetch_emoji_likeA
Read-only

获取表情回应用户(NapCat 分页) 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 后续页原样传回上页 cookie。 Returns: 分页的表情回应用户列表(NapCat 形状),含分页游标 cookie 与首/末页标记。

Inputs: emojiId (required), message_id (required), count, cookie.

fetch_face_entityA
Read-only

按编号查询 QQ 系统表情 Returns: 表情详情;编号不存在时返回 null。

Inputs: face_id (required), refresh.

fetch_ptt_textA
Read-only

获取语音转文字结果 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 Returns: { text }:语音识别出的文本。

Inputs: message_id (required).

fetch_super_face_idB
Read-only

判断 QQ 系统表情是否使用超级表情格式 Returns: 是否使用超级表情格式。

Inputs: face_id (required), refresh.

fetch_sys_facesB
Read-only

获取 QQ 系统表情目录 Returns: 按分组返回完整的 QQ 系统表情映射。

Inputs: refresh.

find_contactA
Read-only

Search friends (by remark, nickname or QQ number) and groups (by name or number). Returns ids to use as targets ("qq:" / "group:").

Inputs: query (required), kind, limit.

forward_friend_single_msgB

转发单条消息给好友 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: user_id (required), message_id (required).

forward_group_single_msgA

转发单条消息到群 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: group_id (required), message_id (required).

forward_messagesA

Forward existing messages (by message_id) to a friend or group — as one 合并转发 bundle (default) or one by one.

Inputs: target (required), message_ids (required), merged.

forward_qzone_public_feedA

将推荐动态转发到当前账号空间 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 只转发,不同时评论或发送给 QQ 联系人。 Returns: 上游转发结果,保留未知字段。

Inputs: feed (required), reason.

friend_pokeC

好友拍一拍 戳一戳指定好友。

Inputs: user_id (required), target_id.

get_ai_charactersA
Read-only

获取 AI 语音角色 将 group_id 替换为当前账号可访问的群号。 Returns: 按分类分组的 AI 语音角色列表,每组含分类名与角色(id、名称、试听 URL)。

Inputs: group_id (required), chat_type.

get_ai_recordA

生成 AI 语音 character 原样使用 get_ai_characters 的 character_id;send_group_ai_record 会直接发送语音。

Inputs: text (required), group_id (required), character (required), chat_type.

get_clientkeyB
Read-only

获取 clientkey 返回值可能包含凭据或临时下载密钥,请勿公开或记录到不受控日志。 Returns: { clientKey, expireTime, keyIndex }:clientkey 及其过期时间与索引。

Inputs: no named parameters.

get_collection_listB
Read-only

获取收藏列表 Returns: 返回收藏条目、是否还有更多数据及底部时间游标。

Inputs: count, category.

get_cookiesA
Read-only

获取 Cookies 返回登录凭据,仅在有明确用途时读取,请勿公开。 Returns: { cookies }:指定域名的 Cookie 字符串。

Inputs: domain.

get_credentialsB
Read-only

获取凭证 返回登录凭据,仅在有明确用途时读取,请勿公开。 Returns: { cookies, token, csrf_token }:Cookie 字符串与 CSRF 令牌(token 与 csrf_token 同值)。

Inputs: domain.

get_csrf_tokenA
Read-only

获取 CSRF 令牌 Returns: { token }:CSRF 令牌(bkn,数值)。

Inputs: no named parameters.

get_doubt_friends_add_requestB
Read-only

获取可疑好友申请 Returns: 可疑好友申请数组,每项含 uid(作为处理用 flag)、昵称、来源、留言与申请时间。

Inputs: count.

get_emoji_likesA
Read-only

获取表情回应用户 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 Returns: { emoji_like_list }:回应该表情的用户列表(nick_name 恒为空串)。

Inputs: emoji_id (required), message_id (required).

get_essence_msg_listB
Read-only

获取精华消息列表 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required).

get_eventsA
Read-only

Raw live events received from QQ (messages, recalls, pokes, join/leave, friend/group requests, file uploads, etc.), oldest first. Use since = the last seq you saw to get only new ones.

Inputs: limit, since, types.

get_fileA
Read-only

获取文件信息(仅图片/语音缓存;群文件请用 get_group_file_url) 仅查询已缓存的图片或语音,先尝试图片,再尝试语音。

Inputs: file, file_id.

get_fileset_idB
Read-only

从 QQ 闪传分享码或官方分享链接获取 fileset_id share_code 使用实际闪传分享链接或提取码。 Returns: { fileset_id }:解析出的文件集 ID。

Inputs: share_code (required).

get_fileset_infoA

获取文件集信息 fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。

Inputs: fileset_id (required).

get_flash_file_listB

获取闪传文件列表 fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。

Inputs: fileset_id (required).

get_flash_file_urlA

获取闪传文件链接 fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。 file_index 从 0 开始。

Inputs: fileset_id (required), file_name, file_index.

get_forward_msgA
Read-only

获取合并转发消息(id 或 message_id) id 是合并转发资源标识,通常来自转发消息段或上传结果 res_id,不是普通数值 message_id。 Returns: { messages }:转发内的消息节点数组(每项为 OneBot 消息事件);reply 保留 id,有内嵌引用内容时附带 message 和可用的 qq/time/seq,可作为转发节点 content 再次发送。

Inputs: id, message_id.

get_friend_dressA
Read-only

获取指定 QQ 号正在使用的个性装扮(挂件/名片/来电/输入状态等) 替换为需要查询的 QQ 号。 Returns: 装扮信息;目标未使用任何可查询装扮时 items 为空数组。网络失败、未登录态/风控、页面改版、返回账号与请求不一致时返回失败并附具体原因

Inputs: user_id (required).

get_friend_listA
Read-only

获取好友列表 Returns: 好友列表,包含账号、昵称、备注及回包已有的公开资料;with_profile=true 时主动补查,失败会报错。未返回的资料省略,零、空字符串和 false 保留。

Inputs: with_profile.

get_friend_msg_historyA
Read-only

获取好友消息历史(无锚点时从服务器获取最新双向记录) 省略 message_id 从最新消息开始;只读取当前账号消息。 Returns: { messages }:好友消息事件对象数组(每项为 OneBot 消息事件,内部字段不固定)。

Inputs: user_id (required), count, message_id, reverse_order.

get_friends_with_categoryA
Read-only

获取分组好友列表 Returns: 好友分组数组;buddyList 与 get_friend_list 使用相同资料字段。默认只使用列表回包,with_profile=true 主动补查,失败会报错;未返回的资料省略。

Inputs: with_profile.

get_group_admin_permissionsA
Read-only

读取指定管理员的撤回、移除成员、每日移除上限及接收验证消息状态 user_id 为目标管理员 QQ 号;包含接收加群验证消息状态。 Returns: 服务器返回的管理员权限;未返回或未指定的开关为 null。每日上限仅在移除权限开启时返回,0 表示不限。

Inputs: user_id (required), group_id (required).

get_group_admin_settingsA
Read-only

获取群管理设置的当前值 将 group_id 替换为当前账号可访问的群号。 Returns: 与对应设置接口字段对齐的当前群管理设置。

Inputs: group_id (required).

get_group_album_listC
Read-only

get_group_album_list 将 group_id 替换为当前账号可访问的群号。 Returns: 群相册列表数组,每项为一个相册的基本信息。

Inputs: group_id (required).

get_group_album_media_listA
Read-only

get_group_album_media_list album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。 下一页传回 nextAttachInfo。 Returns: 相册图片/视频列表及下一页分页游标;视频项包含 id、url、cover、尺寸、时长和多规格地址。

Inputs: album_id (required), group_id (required), attach_info.

get_group_at_all_remainA
Read-only

获取群 @全体成员 剩余次数 将 group_id 替换为当前账号可访问的群号。 Returns: { can_at_all, remain_at_all_count_for_group, remain_at_all_count_for_uin }:@全体可用性与剩余次数。

Inputs: group_id (required).

get_group_detail_infoC
Read-only

获取群详细信息 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required), no_cache.

get_group_files_by_folderB
Read-only

获取群子目录文件列表 将 group_id 替换为当前账号可访问的群号。 Returns: 群文件系统信息(文件与文件夹列表)。

Inputs: group_id (required), folder, folder_id.

get_group_file_system_infoA
Read-only

获取群文件系统信息 将 group_id 替换为当前账号可访问的群号。 Returns: { file_count, limit_count, used_space, total_space }:群文件数量与容量信息(均为服务端实际值)。

Inputs: group_id (required).

get_group_file_urlC
Read-only

获取群文件下载链接 将 group_id 替换为当前账号可访问的群号。 Returns: 群文件下载链接。

Inputs: file_id (required), group_id (required), busid.

get_group_honor_infoB
Read-only

获取群荣誉信息 未请求的分类仍返回空数组;当前龙王可能为 null。

Inputs: group_id (required), type.

get_group_ignore_add_requestB
Read-only

获取被忽略的入群请求(NapCat) Returns: 被忽略的入群请求数组(NapCat 字段命名),每项含请求序列、邀请人、群信息与处理标记。

Inputs: no named parameters.

get_group_ignored_notifiesB
Read-only

获取被过滤的入群请求 Returns: 被过滤的入群请求数组,每项含群号、申请人、邀请人、留言与处理标记。

Inputs: no named parameters.

get_group_infoC
Read-only

获取群信息 将 group_id 替换为当前账号可访问的群号。 Returns: 群信息对象。

Inputs: group_id (required), no_cache.

get_group_info_exC
Read-only

获取群信息(扩展) 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required), no_cache.

get_group_listC
Read-only

获取群列表 Returns: 群信息对象数组。

Inputs: no_cache.

get_group_member_infoC
Read-only

获取群成员信息 将 group_id 替换为当前账号可访问的群号。 Returns: 群成员信息对象。

Inputs: user_id (required), group_id (required), no_cache.

get_group_member_listB
Read-only

获取群成员列表 将 group_id 替换为当前账号可访问的群号。 Returns: 群成员信息对象数组。

Inputs: group_id (required), no_cache.

get_group_msg_historyA
Read-only

获取群消息历史 省略 message_id 从最新消息开始;翻页使用上一页实际 message_id,不要自行加减。 Returns: { messages }:群消息事件对象数组(每项为 OneBot 消息事件,内部字段不固定)。

Inputs: group_id (required), count, message_id, reverse_order.

get_group_noticeA
Read-only

获取群公告 将 group_id 替换为当前账号可访问的群号。 Returns: 普通公告与新成员公告的合并数组;send_to_new_members 标识后者;图片含 id、url、宽高

Inputs: group_id (required).

get_group_root_filesB
Read-only

获取群根目录文件列表 将 group_id 替换为当前账号可访问的群号。 Returns: 群文件系统信息(文件与文件夹列表)。

Inputs: group_id (required).

get_group_shut_listA
Read-only

获取群禁言列表 将 group_id 替换为当前账号可访问的群号。 Returns: 仍在禁言中的成员数组,每项含 QQ 号、昵称与禁言到期时间戳(秒)。

Inputs: group_id (required).

get_group_signed_listA
Read-only

获取群今日打卡列表 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required).

get_group_system_msgA
Read-only

获取群系统消息 将 group_id 替换为当前账号可访问的群号。 Returns: 群系统消息数组,分别提供入群者、邀请人和处理者,可按群号或未处理状态过滤。身份为 0 时须查看状态;未知不代表不存在邀请人。

Inputs: count, group_id, only_pending.

get_group_tagsC
Read-only

读取某个群分类下的资料标签 group_class 使用实际群分类编号。 Returns: 该分类下的资料标签列表。

Inputs: group_class (required).

get_group_todo_listA
Read-only

获取群待办列表 将 group_id 替换为当前账号可访问的群号。 Returns: 群待办数组,包含可用于待办操作的消息标识、服务端摘要与时间

Inputs: group_id (required).

get_imageA
Read-only

获取图片信息 file 或 file_id 原样取自图片消息段,须在当前账号媒体缓存中存在。

Inputs: file, file_id.

get_login_infoB
Read-only

get_login_info Returns: 当前登录账号的 QQ 号与昵称。

Inputs: no named parameters.

get_mini_app_arkB
Read-only

获取小程序卡片 ark 替换为实际分享地址;当前仅支持 bili 和 weibo。返回的 data 是卡片对象,不会自动发送。

Inputs: desc, type, title, picUrl, +3 more.

get_msgA
Read-only

获取消息 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 Returns: 消息事件对象(去除 post_type/self_id,附带 real_id);逐个尝试刷新图片、语音和视频 URL,成功使用新地址,失败保留该段原地址并继续返回消息;地址更新时同步 raw_message。

Inputs: message_id (required).

get_msg_emoji_likesA
Read-only

获取一条消息的全部表情回应 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 Returns: 该消息上每个表情回应的编号、数量与用户列表。

Inputs: message_id (required).

get_online_clientsA
Read-only

获取在线客户端 Returns: { clients }:QQ 本次会话最近推送的在线设备快照。

Inputs: no_cache.

get_private_file_urlA
Read-only

获取私聊文件下载链接 使用私聊文件消息段中的 file_id,必要时原样传 file_hash。 Returns: 私聊文件下载链接。

Inputs: file_id (required), user_id, file_hash.

get_profile_likeC
Read-only

获取资料点赞 Returns: 点赞资料:uid、最近点赞时间、收藏与点赞统计及用户明细。

Inputs: count, start, user_id.

get_qun_album_listA
Read-only

get_qun_album_list 后续页原样传回上一页的 attach_info;has_more=false 表示结束。 Returns: NapCat 风格的相册列表封套:{album_list, attach_info, has_more}。

Inputs: group_id (required), attach_info.

get_qzone_feed_detailA
Read-only

按说说 tid 读取完整空间动态,可用于生成分享卡片 将示例 tid 替换为 get_qzone_msg_list 或 send_qzone_msg 返回的 24 位十六进制说说编号。把结果的 feed 原样传给 get_qzone_share_ark;读取和分享均受空间权限限制。 Rules: tid must be a 24-character hexadecimal post ID. Returns: 完整动态及上游详情字段。feed 保留图片、视频、分享信息和未知字段,可直接用于 get_qzone_share_ark;attach_info 保留上游评论游标,不自动翻页。

Inputs: tid (required), include_html.

get_qzone_feedsA
Read-only

获取 QQ 空间好友动态,支持结构化正文与游标分页 保留 html;content/images 为可提取的正文和图片,未知值为 null。续页使用 next_cursor。 Returns: 好友动态、可提取的正文与图片、统计值及下一页游标;未知内容或统计为 null,HTML 保留。

Inputs: count, cursor, page_num, include_html.

get_qzone_home_feedsB
Read-only

读取自己或有权访问的空间主页动态,保留完整分享信息 Returns: 完整动态及分页状态;访问受空间权限限制,旧说说接口保持不变。

Inputs: cursor, target_uin, include_html.

get_qzone_msg_detailA
Read-only

获取 QQ 空间说说详情与一页评论(含服务端内联回复,需有访问权限) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。 replies 仅为服务端内联回复,不保证完整。 Returns: 说说详情、服务端报告的评论总数与本页评论;replies 仅含服务端内联返回的二级回复,不保证完整。

Inputs: tid (required), num, pos, target_uin.

get_qzone_msg_listA
Read-only

获取 QQ 空间说说列表(默认机器人自己的空间) 默认读取当前账号;指定 target_uin 时需有访问权限。 Returns: 说说列表对象,含说说总数与本页说说数组。

Inputs: num, pos, target_uin.

get_qzone_profileA
Read-only

获取 QQ 空间名称和说明(默认当前账号) 需要有该空间的访问权限。 Returns: 空间名称和说明。

Inputs: target_uin.

get_qzone_public_capabilitiesB
Read-only

读取当前账号的空友爱看入口与推权限 Returns: 当前账号的上游入口能力对象,保留未知字段。

Inputs: no named parameters.

get_qzone_public_commentsA
Read-only

继续读取推荐动态评论 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 先读详情获取初始评论及 attach_info,再原样传入 cursor。 Returns: 上游评论页对象,保留评论、分页和未知字段。

Inputs: feed (required), cursor (required).

get_qzone_public_feed_detailA
Read-only

读取推荐动态详情及初始评论 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 Returns: 上游详情 data;初始评论位于 feed.feed.cell_comment.comments,续页使用 attach_info。

Inputs: feed (required), include_html.

get_qzone_public_feedsA
Read-only

读取空友爱看推荐动态,支持独立游标分页 cursor 原样使用上次返回的 next_cursor,仅适用于同一账号;has_more=false 时停止。 Returns: 推荐动态原始 cell 对象及分页状态,保留其余上游页面字段。

Inputs: cursor, include_html.

get_qzone_public_repliesA
Read-only

继续读取指定评论的回复 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 comment 可取 get_qzone_public_feed_detail 返回的 feed.feed.cell_comment.comments,或后续评论页;保留完整对象。 首次续读使用评论自带的 reply_attach_info;之后传上一回复页的游标。 Returns: 上游回复页对象,保留回复、分页和未知字段。

Inputs: feed (required), comment (required), cursor, page_size.

get_qzone_share_arkA

生成空间动态分享卡片,返回原文及分享提示 feed 原样取自 get_qzone_feed_detail 的 feed,或 get_qzone_home_feeds / get_qzone_public_feeds 的 feeds 条目。分享链接可能允许未登录者访问并包含作者 QQ 号;如 requires_confirmation=true,发送前展示 notice 并取得确认。将 ark 原文作为 JSON 消息发送,不要修改卡片内容。 Returns: 生成卡片但不发送消息;后续发送仍返回普通消息编号。

Inputs: feed (required).

get_recordB
Read-only

获取语音信息;传 out_format 则服务端转码并附带 base64 file 来自语音消息段;格式转换依赖服务端可用的转换工具,成功时增加 out_format 和 base64。 Returns: 语音信息(file/url 为向 QQ 获取的当前下载地址);资源元数据缺失或远端获取失败时返回错误。out_format 指定时附带转码后的 base64。

Inputs: file, file_id, out_format.

get_rkeyB
Read-only

获取下载 rkey 返回值可能包含凭据或临时下载密钥,请勿公开或记录到不受控日志。

Inputs: no named parameters.

get_rkey_serverA
Read-only

获取 rkey 服务器信息 返回值可能包含凭据或临时下载密钥,请勿公开或记录到不受控日志。 Returns: { expired_time, name, private_rkey?, group_rkey? }:rkey 过期时间与(存在时的)私聊/群聊 rkey。

Inputs: no named parameters.

get_statusB
Read-only

get_status Returns: 运行状态。online 表示账号在线;good 表示已确认的收发链路健康状态;time 为当前账号服务实例运行秒数,与 #sl 同源。

Inputs: no named parameters.

get_stranger_infoA
Read-only

获取陌生人信息 替换为需要查询的 QQ 号。 Returns: 用户资料,含账号标识、等级别名和可用的注册时间、生日、会员信息。注册时间、生日或会员信息未返回时省略对应字段,出生年份未公开时只省略年份;登录天数暂无可靠来源,不返回占位值。

Inputs: user_id (required).

get_unidirectional_friend_listC
Read-only

获取单向好友列表

Inputs: no named parameters.

get_unreadB
Read-only

New incoming messages you have not seen yet (since the server started or your last get_unread/read_chat), grouped by chat. Marks them as seen.

Inputs: limit, target, mark_seen.

get_version_infoB
Read-only

get_version_info Returns: 实现与协议版本信息。

Inputs: no named parameters.

group_pokeC

群拍一拍 将 group_id 替换为当前账号可访问的群号。

Inputs: user_id (required), group_id (required).

like_qzoneA

给一条说说点赞(QQ 空间) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。

Inputs: tid (required), abstime, target_uin.

list_contactsA
Read-only

Compact list of all friends and/or groups (target id + display name), with paging. Use refresh=true after adding friends/joining groups.

Inputs: kind, limit, offset, refresh.

list_filesetsB

列出当前账号的所有闪传文件集

Inputs: no named parameters.

list_friend_requestsA
Read-only

Pending friend requests and group join/invite requests seen live, plus the group system message box (入群申请/邀请). Approve with set_friend_add_request / set_group_add_request using the flag.

Inputs: no named parameters.

list_recent_chatsA
Read-only

Chats with activity since the MCP server started (newest first): last message, unread count (messages you have not read via read_chat/get_unread).

Inputs: limit.

list_tools_by_categoryA
Read-only

Overview of every tool grouped by category (message, friend, group_info, group_admin, group_file, group_album, qzone, qzone_web, chat, events, extended…), to find the right one.

Inputs: category.

mark_all_as_readA

标记全部已读 会将当前账号的会话标记为已读。

Inputs: no named parameters.

mark_group_msg_as_readB

标记群消息已读 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required), group_id.

mark_msg_as_readB

标记消息已读(群聊/私聊自动路由) 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required), target_id.

mark_private_msg_as_readB

标记私聊消息已读 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required), user_id.

modify_custom_faceB

修改收藏表情备注 emoji_id 来自 fetch_custom_face_detail。

Inputs: emoji_id (required), desc.

move_custom_face_to_frontB

收藏表情移到最前 emoji_id 来自 fetch_custom_face_detail。

Inputs: emoji_id (required).

move_group_fileC

移动群文件 目录和文件标识均来自该群文件列表。

Inputs: file_id (required), group_id (required), parent_directory (required), target_directory (required).

nc_get_user_statusB
Read-only

获取用户在线/扩展状态 替换为需要查询的 QQ 号。 Returns: { status, ext_status }:用户在线状态码与扩展状态码。

Inputs: user_id (required).

ocr_imageA
Read-only

OCR 图片(服务端,需图片 URL 或已缓存的图片 file_id) 替换为实际可访问的图片地址或已缓存图片标识;不支持本地路径和 base64。 Returns: { texts, language }:识别文本数组(含置信度与坐标)与识别语言。

Inputs: image (required).

onebot_callA

Call any OneBot v11 / extended action of the QQ runtime directly (escape hatch for anything the other tools miss). See list_actions for names.

Inputs: action (required), params, timeout_seconds.

pokeB

戳一戳 someone: a friend in private chat, or a member inside a group.

Inputs: user_id (required), group_id.

qq_clickA

Click on the QQ client window (coordinates as seen in the last qq_screenshot / qq_login image). Returns a fresh screenshot.

Inputs: x (required), y (required), button, double, +1 more.

qq_loginA
Read-only

Log in to QQ. If not logged in, returns a screenshot of the QQ login window: show the QR code to the user and ask them to scan it with the QQ phone app (扫一扫) and confirm on the phone. If the window shows a "登录"/"进入QQ" button for a remembered account instead, click it with qq_click. Call qq_login_status afterwards (or wait=true here).

Inputs: wait.

qq_login_statusA
Read-only

Is QQ logged in and connected? Returns the account if so.

Inputs: no named parameters.

qq_restart_clientA
Destructive

Restart the QQ desktop client (use when it is stuck, crashed, or to get a fresh login QR code). Messages cannot be sent for ~20s while it restarts.

Inputs: no named parameters.

qq_screenshotA
Read-only

Screenshot of the virtual display the QQ client runs on (the QQ window by default, or the full screen). Use it to see dialogs such as login prompts, security checks or update notices.

Inputs: full_screen.

qq_typeA

Type text or press keys in the focused QQ window (e.g. a verification code). keys uses xdotool names: "Return", "Tab", "ctrl+a", "BackSpace", "Escape".

Inputs: keys, text.

qq_watchdogB
Read-only

State of the login watchdog that keeps QQ logged in automatically (re-clicks 登录 for the remembered account, dismisses 下线 pop-ups, restarts a stuck client, notifies when a QR scan is really needed). check_now=true runs a check immediately.

Inputs: check_now.

qzone_album_photosA
Read-only

List photos in a personal 空间相册 album (with full-size URLs). Use view_image url=… to look at one.

Inputs: album_id (required), num, uin, start.

qzone_albumsA
Read-only

List personal 空间相册 albums (yours by default) with ids, photo counts and privacy.

Inputs: uin.

qzone_board_deleteA
Destructive

Delete a 留言板 message (on your own board, or one you wrote elsewhere).

Inputs: author_uin (required), message_id (required), uin.

qzone_board_listB
Read-only

Read a 空间 留言板 (message board) — yours by default — with replies.

Inputs: num, uin, start.

qzone_board_postC

Write a message on someone's 留言板 (or your own).

Inputs: uin (required), content (required).

qzone_board_replyC

Reply to a message on a 留言板 (usually your own).

Inputs: content (required), message_id (required), uin.

qzone_create_albumC

Create a personal 空间相册 album.

Inputs: name (required), desc, priv.

qzone_delete_albumA
Destructive

Delete one of your personal 空间相册 albums together with its photos.

Inputs: album_id (required).

qzone_delete_commentA
Destructive

Delete a comment under a 说说 (any comment on your own 说说, or your own comment elsewhere).

Inputs: tid (required), comment_id (required), comment_uin (required), uin.

qzone_delete_photosA
Destructive

Delete photos from one of your 空间相册 albums (photo ids from qzone_album_photos).

Inputs: album_id (required), photo_ids (required).

qzone_forwardB

转发 a 说说 to your own 空间, with an optional comment.

Inputs: tid (required), uin (required), content.

qzone_friendsB
Read-only

Friends as QQ空间 sees them, with 空间 grouping and 亲密度 (intimacy score).

Inputs: no named parameters.

qzone_intimacyB
Read-only

空间 friendship ranking: who you care about most (mine) or who cares about you most (theirs), by 亲密度.

Inputs: direction.

qzone_like_listB
Read-only

Who liked a 说说 (names and QQ numbers).

Inputs: tid (required), uin, count.

qzone_post_countsB
Read-only

View / like / comment / forward counts of a 说说.

Inputs: tid (required), uin.

qzone_requestA

Call any QQ空间 web CGI with your logged-in cookies and g_tk added automatically (escape hatch). url: full https URL, or "host/path" sent via the h5.qzone.qq.com proxy, e.g. "taotao.qq.com/cgi-bin/emotion_cgi_msglist_v6". Parses JSON/JSONP/frameElement.callback responses.

Inputs: url (required), form, query, method.

qzone_user_cardB
Read-only

Someone's 空间 name card (nickname, avatar, 空间 name, whether you can visit, etc.).

Inputs: uin (required).

qzone_visitorsA
Read-only

QQ空间 访客记录: who visited a 空间 recently (yours by default; others need permission), with time and source.

Inputs: uin, page.

read_chatA
Read-only

Read the latest messages of a private or group chat as readable lines (oldest first). Page back with before_message_id = the oldest message_id you got. Marks the chat as read for get_unread. Note: older server history is reachable once the chat has had at least one message since QQ logged in on the server; everything seen since then is kept.

Inputs: target (required), count, mark_read_on_qq, before_message_id.

rename_flash_fileB

重命名闪传文件 fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。

Inputs: new_name (required), fileset_id (required).

rename_group_fileB

重命名群文件 file_id 来自群文件列表,目录必须是文件当前所在目录。

Inputs: file_id (required), group_id (required), new_name (required), current_parent_directory.

rename_group_file_folderC

重命名群文件夹 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required), folder_id (required), name, new_folder_name.

reply_qzone_public_feedA

回复推荐动态的评论或其中某条回复 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 comment 可取 get_qzone_public_feed_detail 返回的 feed.feed.cell_comment.comments,或后续评论页;保留完整对象。 Returns: 上游回复结果,包含新回复,保留未知字段。

Inputs: feed (required), comment (required), content (required), reply.

reply_to_messageA

Quote-reply to a message by its message_id (works for group and private messages). Optionally @ the original sender.

Inputs: text (required), message_id (required), mention_sender.

request_decrypt_keyA

请求数据库解密密钥 路径位于 SnowLuma 服务端,必须指向当前账号可用的数据库;返回值是敏感密钥。

Inputs: db_path (required).

search_chatB
Read-only

Find messages containing a keyword (case-insensitive) in one chat by scanning its history backwards.

Inputs: target (required), keyword (required), scan, from_user.

search_sys_facesB
Read-only

搜索 QQ 系统表情 Returns: 匹配编号、名称、别名或分组名的表情列表。

Inputs: query (required).

send_ark_shareB
Read-only

分享用户/群 Ark 卡片(NapCat 标准名) 生成联系人分享卡片;返回卡片数据,不等同于发送到聊天。 Returns: { arkMsg }:服务端生成的推荐联系人 Ark 卡片 JSON 字符串。

Inputs: user_id, group_id, phone_number.

send_custom_faceA

发送账号收藏表情(emoji_id 或 MD5),保留表情显示样式 群聊和私聊目标只能提供一个;emoji_id 来自 fetch_custom_face_detail。 Returns: { message_id: number }

Inputs: emoji_id (required), user_id, group_id, reply_to.

send_fake_forwardA

Send a 合并转发 card built from custom nodes (each with a display name, QQ number and content), e.g. to share a summary as a chat transcript.

Inputs: nodes (required), target (required), source, summary.

send_fileA

Send a file to a friend or upload it to a group (群文件). Source: URL, path on the server, or base64.

Inputs: file (required), target (required), name, folder_id.

send_flash_msgA

发送闪传消息(私聊或群聊,引用 fileset_id 让对端下载) fileset_id 来自 create_flash_task、get_fileset_id 或 list_filesets,替换为当前账号可访问的文件集。 会发送分享消息;message_id=0 是占位值,不能用于撤回或查消息。 Returns: { message_id }

Inputs: fileset_id (required), user_id, group_id.

send_forward_msgB

发送合并转发(按 message_type/群号自动路由) 替换目标群号;nodes 是自定义转发节点数组。send_forward_msg 不提供目标时仅上传资源并返回 message_id=0。 Returns: { message_id, res_id, forward_id }

Inputs: news, prompt, source, message, +5 more.

send_group_ai_recordA

发送 AI 语音到群 character 原样使用 get_ai_characters 的 character_id;send_group_ai_record 会直接发送语音。 Returns: { message_id }:已发送 AI 语音的 OneBot 消息 ID。

Inputs: text (required), group_id (required), character (required), chat_type.

send_group_ark_shareA
Read-only

分享群 Ark 卡片(NapCat 标准名) 生成群分享卡片;返回卡片数据,不等同于发送到聊天。 Returns: 服务端生成的群推荐 Ark 卡片 JSON 字符串。

Inputs: group_id (required).

send_group_forward_msgB

发送群合并转发 替换目标群号;nodes 是自定义转发节点数组。send_forward_msg 不提供目标时仅上传资源并返回 message_id=0。 Returns: { message_id, res_id, forward_id }

Inputs: group_id (required), news, prompt, source, +3 more.

send_group_msgB

发送群消息 替换目标群号;成功返回的 message_id 可为负值。 Returns: { message_id: number }

Inputs: message (required), group_id (required), auto_escape.

send_group_noticeB

发送群公告(支持置顶、弹窗、新成员、群昵称引导与确认) 需要群公告管理权限;普通公告 type=1,新成员公告 type=20。 Rules: type must be 1 (regular) or 20 (new members); send_to_new_members conflicts with type.

Inputs: content (required), group_id (required), type, image, +5 more.

send_imageA

Send a picture (http(s) URL, local path on the server, file://, or base64) to a friend or group, optionally with a caption. Set as_sticker to send it as a 表情 sticker.

Inputs: image (required), target (required), caption, as_sticker.

send_likeD

点赞

Inputs: user_id (required), times.

send_messageA

Send any OneBot message to a friend or group: a CQ-code string or an array of segments, e.g. [{"type":"text","data":{"text":"hi"}},{"type":"image","data":{"file":"https://…"}}]. Segment types: text, at, face, mface, image, record, video, file, reply, forward, json, xml, poke, dice, rps, music, contact, markdown, location, share.

Inputs: target (required), message (required).

send_msgA

发送消息(按 message_type/群号 自动路由群聊或私聊) 必须提供对应目标;私聊使用 message_type=private 和 user_id。 Returns: { message_id: number }

Inputs: message (required), user_id, group_id, auto_escape, +1 more.

send_packetB

发送原始 SSO 包(cmd + hex data) 仅供有协议经验的调用方:cmd 和 data 必须成对替换为已验证的命令与十六进制请求;示例占位符不可直接发送。

Inputs: cmd (required), rsp, data.

send_pokeB

拍一拍(群聊/私聊自动路由) 将 group_id 替换为当前账号可访问的群号。

Inputs: user_id (required), group_id.

send_private_forward_msgB

发送私聊合并转发 替换目标好友 QQ 号。 Returns: { message_id, res_id, forward_id }

Inputs: user_id (required), news, prompt, source, +3 more.

send_private_msgB

发送私聊消息 替换目标好友 QQ 号;临时会话需另传来源 group_id。 Returns: { message_id: number }

Inputs: message (required), user_id (required), group_id, auto_escape.

send_qzone_msgA

发表说说(QQ 空间,支持纯文字或带图;传 images 自动上传;可设置查看权限) 会发布说说;ugc_right=64 仅自己可见。16/128 还必须提供 target_uins。 Rules: ugc_right must be one of 1, 4, 16, 64, 128; target_uins is required when ugc_right is 16 or 128.

Inputs: content (required), images, ugc_right, target_uins.

send_textB

Send a text message to a friend or group. Inline tokens: [@QQ号] mention, [@all] @全体, [face:ID] QQ emoji, [reply:message_id] quote, [image:URL或路径] picture. Or use reply_to / mention.

Inputs: text (required), target (required), mention, reply_to.

send_tuwen_arkC

发送图文 Ark 卡片(私聊/群聊) 替换目标群号及实际链接;会发送分享卡片。 Returns: null

Inputs: desc (required), title (required), jump_url (required), summary, +3 more.

send_videoB

Send a video (mp4 from URL, path or base64).

Inputs: file (required), target (required), thumb.

send_voiceA

Send a voice message (mp3/wav/silk/amr… from URL, path or base64; converted automatically).

Inputs: file (required), target (required).

set_diy_online_statusC

设置自定义在线状态

Inputs: face_id (required), wording, face_type.

set_doubt_friends_add_requestC

处理可疑好友申请 flag 使用 get_doubt_friends_add_request 返回项的 uid。

Inputs: flag (required), approve.

set_essence_msgA

设置精华消息 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: message_id (required).

set_friend_add_requestB

处理好友添加请求 flag 必须原样使用当前账号好友请求事件的 flag,不能根据 QQ 号构造。

Inputs: flag (required), approve.

set_friend_remarkC

设置好友备注

Inputs: remark (required), user_id (required).

set_friends_categoryA

移动好友到指定分组 categoryId 与 categoryName 二选一。 Rules: exactly one of: categoryId | categoryName. Returns: 成功时返回空数据。

Inputs: uin (required), categoryId, categoryName.

set_group_add_optionB

设置加群选项 修改加群设置前先用 get_group_admin_settings 查看当前状态,并确认目标设置值。

Inputs: group_id (required), add_type, group_answer, group_question.

set_group_add_requestC

处理加群请求 flag 和 sub_type 原样取自同一条群请求事件;邀请事件使用 invite。

Inputs: flag (required), type, reason, approve, +1 more.

set_group_adminA

设置/取消管理员 需要群主权限;会授予该成员管理员身份。

Inputs: user_id (required), group_id (required), enable.

set_group_admin_permissionsA

设置指定管理员的撤回和移除成员权限 需要当前账号具有修改权限;不会授予管理员角色。仅修改显式字段。开启移除必须提供上限,0 表示不限;修改上限需同时传 kick_member=true。 Rules: at least one of: recall_member_message, kick_member; kick_member=true requires kick_member_per_day: 0, 5, 10, 20, 50, 100 or 200; kick_member_per_day requires kick_member=true.

Inputs: user_id (required), group_id (required), kick_member, kick_member_per_day, +1 more.

set_group_admin_receive_verifyA

设置指定管理员是否接收加群验证消息 user_id 为目标管理员 QQ 号;需要当前账号具有修改权限。独立于撤回和移除成员权限。

Inputs: enable (required), user_id (required), group_id (required).

set_group_album_media_likeB

set_group_album_media_like album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。 batch_id 必须是实际批次的十进制字符串。

Inputs: album_id (required), batch_id (required), group_id (required), lloc.

set_group_banA
Destructive

禁言群成员(duration=0 解除) 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。 duration 为秒,0 表示解除禁言。

Inputs: user_id (required), group_id (required), duration.

set_group_cardB

设置群名片(空字符串清除) 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: user_id (required), group_id (required), card.

set_group_kickB
Destructive

踢出群成员 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: user_id (required), group_id (required), reject_add_request.

set_group_kick_membersB
Destructive

批量踢出群成员 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: user_id (required), group_id (required), reject_add_request.

set_group_leaveA
Destructive

退群 会退出该群,请确认目标群号后调用。

Inputs: group_id (required).

set_group_member_invite_policyC

设置群成员邀请策略 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: policy (required), group_id (required).

set_group_member_permissionsA

设置群成员权限(仅群主可改) 至少传一个权限字段;仅修改传入的权限,其余保持原样。 Rules: at least one of: allow_member_upload_album, allow_member_temporary_session, allow_member_create_group.

Inputs: group_id (required), allow_member_create_group, allow_member_upload_album, allow_member_temporary_session.

set_group_nameA

设置群名 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: group_id (required), group_name.

set_group_new_member_history_visibilityB

设置新成员是否可查看历史消息 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: visible (required), group_id (required).

set_group_portraitB

设置群头像 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。

Inputs: file (required), group_id (required).

set_group_reactionB

群聊表情回应 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: code (required), message_id (required), is_set, group_id.

set_group_remarkC

设置群备注 将 group_id 替换为当前账号可访问的群号。

Inputs: remark (required), group_id (required).

set_group_robot_add_optionC

设置群机器人加群选项 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: group_id (required), robot_member_switch, robot_member_examine.

set_group_signC

群签到 将 group_id 替换为当前账号可访问的群号。

Inputs: group_id (required).

set_group_special_titleB

设置群头衔 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: user_id (required), group_id (required), special_title.

set_group_todoA

设置群待办 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。 必须是该群的消息。

Inputs: group_id (required), message_id (required).

set_group_whole_banC
Destructive

全员禁言开关 替换群号和成员 QQ 号;操作是否允许取决于当前账号在该群的权限。

Inputs: group_id (required), enable.

set_input_statusD

设置输入状态

Inputs: user_id (required), event_type.

set_msg_emoji_likeA

设置消息表情回应 使用消息事件或发送结果中的真实 message_id,负值合法;消息须在当前账号的消息存储中可查询。

Inputs: emoji_id (required), message_id (required), set.

set_online_statusC

设置在线状态 修改当前账号状态;具体状态码须与目标状态对应。

Inputs: status (required), ext_status, battery_status.

set_qq_avatarB

设置 QQ 头像 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。

Inputs: file (required).

set_qq_profileB

设置 QQ 资料 会修改当前账号的资料;只传入需要修改的字段。

Inputs: sex, nickname, personal_note.

set_qzone_banA

拉黑或解除拉黑某人(修改机器人自身 QQ 空间黑名单;enable=true 拉黑,false 解除) 修改当前账号空间黑名单。

Inputs: user_id (required), enable.

set_qzone_msg_rightA

修改一条已发说说的查看权限(QQ 空间,按 tid) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。 16 表示仅所选好友可见。 Rules: ugc_right must be one of 1, 4, 16, 64, 128; target_uins is required when ugc_right is 16 or 128. Returns: 更新后的权限对象。

Inputs: tid (required), ugc_right (required), target_uins.

set_qzone_profileA

修改当前账号的 QQ 空间名称或说明 仅修改提供的字段;空字符串表示清空对应字段。 Rules: at least one of: name, description.

Inputs: name, description.

set_qzone_public_comment_likeA

点赞或取消赞推荐动态中的评论或回复 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 comment 可取 get_qzone_public_feed_detail 返回的 feed.feed.cell_comment.comments,或后续评论页;保留完整对象。 必须保留评论原始 like.id。 Returns: 上游普通赞操作结果,保留未知字段。

Inputs: feed (required), comment (required), reply, enable.

set_qzone_public_followA

蹲或取消蹲推荐动态作者 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 feed 需保留作者 cell_user_info。 Returns: 上游关系操作结果,保留未知字段。

Inputs: feed (required), enable.

set_qzone_public_likeA

点赞或取消赞推荐动态 feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 Returns: 上游普通赞操作结果,保留未知字段。

Inputs: feed (required), enable.

set_qzone_public_upvoteA

推或取消推空友爱看动态(独立于普通赞) feed 必须原样取自 get_qzone_public_feeds 的 feeds 数组,不能用旧说说 tid 拼造;示例中的占位字段须整体替换。 Returns: 上游推操作结果,保留未知字段。

Inputs: feed (required), enable.

set_self_longnickC

设置个性签名(longNick/long_nick,严格 string)

Inputs: longNick, long_nick.

share_group_exA
Read-only

分享群 Ark 卡片 生成群分享卡片;返回卡片数据,不等同于发送到聊天。 Returns: 服务端生成的群推荐 Ark 卡片 JSON 字符串。

Inputs: group_id (required).

share_peerA
Read-only

分享用户/群 Ark 卡片 生成联系人分享卡片;返回卡片数据,不等同于发送到聊天。 Returns: { arkMsg }:服务端生成的推荐联系人 Ark 卡片 JSON 字符串。

Inputs: user_id, group_id, phone_number.

test_download_streamA

测试下载流(推送 10 个数据帧,验证流式传输,不触达 QQ) 经 invoke_action 调用,仅测试传输,不访问 QQ。 Returns: 流式帧:data_chunk*10 → data_complete(error=true 时以 error 帧结束)

Inputs: error.

trans_group_fileC

转存群文件 替换群文件列表中的实际 file_id;需要对应文件操作权限。 Returns: { ok: true }

Inputs: file_id (required), group_id (required).

translate_en2zhB
Read-only

英译中 Returns: { words }:与输入等长的中文译文字符串数组。

Inputs: words (required).

unlike_qzoneA

取消对一条说说的点赞(QQ 空间;取消赞端点待真机核实) tid 来自 get_qzone_msg_list;操作需有该说说的访问或管理权限。

Inputs: tid (required), abstime, target_uin.

upload_file_streamA

以流式分块方式上传文件到机器人本地(返回可用于发送的本地路径) 第 1 步:每次上传生成新的 stream_id;这里上传 hello 的唯一分块。通过 invoke_action 调用,分块确认不等于整文件完成。 Returns: 流式帧:分块确认 type=stream、完成 type=response(含 file_path/file_name/file_size/sha256)

Inputs: stream_id (required), reset, filename, file_size, +7 more.

upload_forward_msgA

上传转发消息 仅上传合并转发资源,不发送聊天消息;message_id=0 是占位值,后续使用 res_id。

Inputs: message, group_id, messages.

upload_group_fileC

上传群文件 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。 Returns: { file_id: string }

Inputs: file (required), group_id (required), name, folder, +2 more.

upload_image_to_qun_albumB

upload_image_to_qun_album album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。

Inputs: file (required), album_id (required), group_id (required), album_name (required).

upload_private_fileB

上传私聊文件 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。 默认上传并发送给该好友。 Returns: { file_id: string }

Inputs: file (required), user_id (required), name, upload_file.

upload_video_to_qun_albumA

上传视频到群相册 album_id 来自 get_group_album_list;lloc 或视频 id、batch_id 来自 get_group_album_media_list。替换群号及对应资源标识。 示例路径位于 SnowLuma 服务端,须替换为该服务可读取的实际文件。 Returns: { id: string }

Inputs: file (required), album_id (required), group_id (required), album_name (required).

view_imageA
Read-only

Look at a picture: pass a message_id (first image in that message), an image URL, a local path, or an image file id. Returns the image so you can see it.

Inputs: url, file, index, message_id.

wait_for_eventA
Read-only

Block until an event of the given types arrives (e.g. "notice.group_increase", "request.friend", "notice.group_recall").

Inputs: types (required), timeout_seconds.

wait_for_messageA
Read-only

Block until a new message arrives (optionally only from a chat / sender / containing text), up to timeout_seconds. Good for "reply when they answer" flows.

Inputs: target, contains, from_user, include_self, +1 more.

whoamiA
Read-only

Who is logged in: QQ number, nickname, online status, and how many friends/groups. Start here.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 260 tools

    Disambiguation2/5

    The surface contains numerous near-duplicate or heavily overlapping tools: send_text/send_message/send_msg/send_private_msg/send_group_msg, forward_messages/forward_friend_single_msg/forward_group_single_msg/send_forward_msg/send_group_forward_msg/send_private_forward_msg/upload_forward_msg, share_peer/send_ark_share/share_group_ex/send_group_ark_share, fetch_emoji_like/get_emoji_likes/get_msg_emoji_likes, and delete_group_file_folder/delete_group_folder appear to do the same thing. An agent would frequently have to guess between aliases and layered wrappers (NapCat-style vs SnowLuma-style vs OneBot-style) with no clear selection rule. Some families (group info, group admin, Qzone) are distinguishable, but the messaging and forwarding clusters are badly blurred.

    Naming Consistency2/5

    Names mostly use verb_noun snake_case, but the set mixes prefixes and conventions: qq_login/qq_screenshot/qq_watchdog alongside bare send_text, get_msg, poke, mark_all_as_read, plus odd forms like nc_get_user_status, do_group_album_comment, clean_cache, and duplicate aliases such as get_group_album_list vs get_qun_album_list. There is no single predictable pattern an agent can rely on, and same-purpose tools land in different naming families.

    Tool Count1/5

    260 tools is far beyond any reasonable agent-facing surface for a QQ client; almost every OneBot action plus Qzone CGI plus raw SSO/credential helpers is exposed individually. Many tools are redundant shims (aliases, escape hatches, capability probes, stream-test helpers) that inflate the list without adding capability. The server would have been far more coherent with a scoped core of 15-25 tools plus one escape hatch.

    Completeness4/5

    Coverage is effectively exhaustive: messaging, media, group info/admin/files/albums, friend handling, events, and extensive Qzone read/write operations are all present, with escape hatches (onebot_call, qzone_request, send_packet) filling any remaining gap. The only completeness concerns are minor (some operations only reachable via escape hatches), so the surface itself has no obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to control and monitor QQ accounts through the NapCatQQ OneBot 11 protocol, covering private/group messaging, forwards, group administration, file transfer, OCR, friend and profile management, and real-time message listening. It also handles QR-code login, hot-switching between multiple QQ accounts, and one-click self-check, deployment, and updates.
      20
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables users to send messages, manage QQ groups and channels, upload rich media, and receive gateway events through QQ official bot OpenAPI tools. It also provides a Chinese interactive CLI for the same operations.
      13
      33 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI QQ bot to call installed plugins as MCP tools for group management, long-term memory, text-to-speech, image generation, reminders, accounting, utilities, and mini-games. It also provides a web market for installing, configuring, and managing those plugins through SnowLuma/OneBot.
      6
      MIT