How do I use qq-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qq-mcp-server list all my groups" 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.

qq-mcp-server

by print-yuhuan

Overview Schema Related Servers Score Discussions

Python

Remote

qq-mcp-server

一个基于 MCP 的服务端，通过 Streamable HTTP 对外提供 QQ 机器人能力。它让各类 MCP 客户端 —— Claude Desktop、Codex、Cherry Studio、Cursor、Cline、Trae 等 —— 能够查询 QQ 机器人状态、读取群与好友信息、拉取聊天记录，以及发送群聊 / 私聊文本消息。

服务端对内调用由 你自己 部署并配置好的 NapCatQQ OneBot HTTP API。本项目只交付 qq-mcp-server；NapCatQQ 的安装、登录与维护不在交付范围内。

MCP 客户端  ──Streamable HTTP（MCP, JSON-RPC）──▶  qq-mcp-server  ──OneBot HTTP──▶  NapCatQQ  ──▶  QQ
            （Authorization: Bearer / X-API-Key / ?token=）       （Authorization: Bearer）

功能特性

MCP Streamable HTTP 传输（JSON-RPC over HTTP）。
三种鉴权方式，均校验同一个 token： Authorization: Bearer、X-API-Key、?token=（可开关）。
对 NapCatQQ OneBot HTTP API 的轻量、文档清晰的封装。
10 个 MCP 工具，覆盖状态查询、列表查询、历史记录、消息发送与群管理。
严格的参数校验、统一的 { "ok": ... } 返回结构，以及可读的错误码。
基于 .env 的配置，并提供开箱即用的 systemd 部署方案。

Related MCP server: Amadeus-QQ-MCP

环境要求

Python 3.10+
一个已运行且配置完成的 NapCatQQ HTTP 服务器（OneBot v11 HTTP），可被本服务访问，且已启用 Token。

NapCatQQ 仓库：https://github.com/NapNeko/NapCatQQ · 文档：https://napneko.github.io/

安装

git clone <YOUR_REPO_URL> qq-mcp-server
cd qq-mcp-server

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e .                   # 或：pip install -r requirements.txt

配置

复制示例文件并填入你自己的值：

cp .env.example .env

变量	是否必填	默认值	说明
`QQ_MCP_HOST`	否	`0.0.0.0`	MCP 服务监听地址。
`QQ_MCP_PORT`	否	`8888`	MCP 端点端口。
`QQ_MCP_PATH`	否	`/mcp`	MCP 端点的 URL 路径。
`QQ_MCP_ACCESS_TOKEN`	是	—	MCP 客户端必须携带的 token。
`QQ_MCP_ENABLE_QUERY_TOKEN`	否	`true`	是否允许 `?token=` 方式。
`NAPCAT_BASE_URL`	是	—	NapCat HTTP 服务器的基础 URL。
`NAPCAT_ACCESS_TOKEN`	否	空	NapCat HTTP 服务器的 Token。
`NAPCAT_TIMEOUT_SECONDS`	否	`30`	调用 NapCat 的单次超时时间。
`QQ_MCP_LOG_LEVEL`	否	`INFO`	`DEBUG`/`INFO`/`WARNING`/`ERROR`。
`QQ_MCP_LOG_MESSAGE_CONTENT`	否	`false`	是否记录发送消息的内容。
`QQ_MCP_MAX_MESSAGE_CHARS`	否	`5000`	单条发送消息的最大字符数。
`QQ_MCP_DEFAULT_HISTORY_COUNT`	否	`5`	默认历史拉取条数。
`QQ_MCP_MAX_HISTORY_COUNT`	否	`1000`	最大历史拉取条数。

NAPCAT_BASE_URL 示例（按你的部署拓扑选择其一）：

# qq-mcp-server 与 NapCat 部署在同一台主机：
NAPCAT_BASE_URL=http://127.0.0.1:<NAPCAT_PORT>
NAPCAT_ACCESS_TOKEN=<NAPCAT_ACCESS_TOKEN>

# qq-mcp-server 与 NapCat 部署在不同主机：
NAPCAT_BASE_URL=http://<NAPCAT_HOST>:<NAPCAT_PORT>
NAPCAT_ACCESS_TOKEN=<NAPCAT_ACCESS_TOKEN>

运行

python -m qq_mcp_server
# 或在执行过 `pip install -e .` 后：
qq-mcp-server

MCP 端点即为 http://<HOST>:<PORT><PATH>（默认 http://<HOST>:8888/mcp）。另提供一个 GET /health 端点（无需鉴权）用于存活探测。

连接 MCP 客户端

在客户端中填入 MCP URL，并选择三种鉴权方式之一。

Authorization Bearer 请求头（推荐）：

URL：         http://<HOST>:<PORT>/mcp
请求头名称：  Authorization
请求头值：    Bearer <MCP_ACCESS_TOKEN>

X-API-Key 请求头：

URL：         http://<HOST>:<PORT>/mcp
请求头名称：  X-API-Key
请求头值：    <MCP_ACCESS_TOKEN>

token 查询参数（需要 QQ_MCP_ENABLE_QUERY_TOKEN=true）：

http://<HOST>:<PORT>/mcp?token=<MCP_ACCESS_TOKEN>

若后续启用 HTTPS / 域名 / 反向代理，请保持相同的 MCP 路径与 token 传参方式，例如 https://<HOST>:<PORT>/mcp?token=<MCP_ACCESS_TOKEN>。

工具列表

所有工具均返回统一结构（见返回结构）。 读 表示只读工具；写 表示会真实修改 QQ 状态的工具。

工具	类型	入参	用途
`qq_get_bot_status`	读	—	在线状态、机器人 QQ 号与昵称。
`qq_list_groups`	读	—	已加入的群：`group_id`、`group_name`、`member_count`。
`qq_list_friends`	读	—	好友：`user_id`、`nickname`、`remark`。
`qq_get_group_members`	读	`group_id`	群成员：`user_id`、`card`、`nickname`、`role`。
`qq_get_group_messages`	读	`group_id`、`count`、`start_message_seq`、`reverse_order`、`parse_forward`	群聊历史记录。
`qq_get_private_messages`	读	`user_id`、`count`、`start_message_seq`、`reverse_order`、`parse_forward`	私聊历史记录。
`qq_send_group_text`	写	`group_id`、`text`	会真实发送群文本消息。
`qq_send_private_text`	写	`user_id`、`text`	会真实发送私聊文本消息。
`qq_set_group_ban`	写 / 高风险	`group_id`、`user_id`、`duration`	禁言/解禁某成员（`duration` 单位秒；`0` 表示解禁）。
`qq_set_group_whole_ban`	写 / 高风险	`group_id`、`enable`	开启/关闭全员禁言。

历史类工具：count 默认取 QQ_MCP_DEFAULT_HISTORY_COUNT，且不得超过 QQ_MCP_MAX_HISTORY_COUNT。使用 start_message_seq 进行翻页，reverse_order 反转排序， parse_forward 额外解析合并转发消息。高风险管理类工具要求机器人在目标群具备管理员权限，否则 NapCat 会返回失败。

返回结构

成功：

{ "ok": true, "data": { } }

失败：

{
  "ok": false,
  "error": {
    "code": "NAPCAT_REQUEST_FAILED",
    "message": "Could not reach the NapCat HTTP server",
    "detail": {}
  }
}

错误码可帮助客户端区分问题类型：

错误码	含义
`INVALID_PARAMS`	参数缺失或格式错误。
`MESSAGE_TOO_LONG`	`text` 超过 `QQ_MCP_MAX_MESSAGE_CHARS`。
`INVALID_DURATION`	`duration` 为负数或非整数。
`NAPCAT_REQUEST_FAILED`	NapCat HTTP 服务器不可达 / 超时 / 响应异常。
`NAPCAT_AUTH_FAILED`	NapCat 拒绝了 OneBot Token。
`NAPCAT_API_ERROR`	NapCat 返回非 `ok` 结果（如群号/QQ 错误、缺少管理员权限、机器人离线等）。
`INTERNAL_ERROR`	服务端未预期的内部错误。

MCP 鉴权失败会在 HTTP 层返回 401，错误码为 MCP_AUTH_FAILED。

验证服务

存活检查：

curl -i "http://<HOST>:<PORT>/health"

底层 MCP initialize 握手（在接入真实 MCP 客户端前，便于排查客户端配置问题）。注意必须携带 Accept 请求头：

curl -i "http://<HOST>:<PORT>/mcp" \
  -H "Authorization: Bearer <MCP_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"test"}}}'

预期结果：返回 HTTP 200，Content-Type 为 application/json 或 text/event-stream，内容包含 JSON-RPC 的 initialize 结果。若返回 401/403，说明 MCP token 或鉴权请求头配置有误。

使用 systemd 部署（Linux）

假设项目位于 /root/qq-mcp-server，并已创建 .venv：

# 1. 安装
cd /root/qq-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .

# 2. 配置（不纳入版本管理）
cp deploy/qq-mcp-server.env.example /root/qq-mcp-server/qq-mcp-server.env
chmod 600 /root/qq-mcp-server/qq-mcp-server.env
nano /root/qq-mcp-server/qq-mcp-server.env      # 填入真实值

# 3. 服务
cp deploy/qq-mcp-server.service /etc/systemd/system/qq-mcp-server.service
systemctl daemon-reload
systemctl enable --now qq-mcp-server.service

服务管理命令：

systemctl status qq-mcp-server.service
systemctl restart qq-mcp-server.service
systemctl stop qq-mcp-server.service
systemctl start qq-mcp-server.service
journalctl -u qq-mcp-server.service -f

如果安装到其他目录，请相应修改 unit 文件中的 WorkingDirectory、ExecStart 与 EnvironmentFile。

安全说明

MCP 端点可能暴露在公网，请妥善保管 QQ_MCP_ACCESS_TOKEN 并使用足够长的随机值。
NapCat HTTP 服务器必须启用自身的 Token；本服务始终向 NapCat 发送 Authorization: Bearer。
?token= 方式较为方便，但 token 可能进入日志 / 代理记录 —— 如不需要，可通过 QQ_MCP_ENABLE_QUERY_TOKEN=false 关闭。
qq_set_group_ban 与 qq_set_group_whole_ban 会真实修改群状态，请仅向可信客户端开放本服务。
默认关闭消息内容日志；仅在可信环境下临时将 QQ_MCP_LOG_MESSAGE_CONTENT=true 用于调试。
本服务不内置 HTTPS。生产环境建议在反向代理处终止 TLS，并/或通过防火墙、IP 白名单限制访问来源。

开发与测试

pip install -e ".[dev]"
pytest

测试使用假 token、假 URL 和 mock 的 NapCat 响应，无需任何真实凭据或网络访问。

许可证

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/print-yuhuan/qq-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server