Skip to main content
Glama
print-yuhuan

qq-mcp-server

by print-yuhuan
OverviewSchemaRelated ServersScoreDiscussions
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

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Servers

  • DDG MCP2 Server

    elliotnorrevik
    -
    license
    -
    quality
    -
    maintenance
    A basic MCP server built with FastMCP framework that provides simple utility tools including message echoing and server information retrieval. Supports both stdio and HTTP transports with Docker deployment capabilities.

  • Amadeus-QQ-MCP

    JulesLiu390
    A
    license
    A
    quality
    D
    maintenance
    An 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.
    7
    24
    MIT

  • WhatsApp MCP Stream

    loglux
    A
    license
    B
    quality
    C
    maintenance
    An MCP server that enables interaction with WhatsApp using the Baileys library and Streamable HTTP transport. It supports managing contacts, chats, and messages, while providing a web admin UI for QR code authentication and media handling.
    28
    5
    MIT

  • io.github.daedalus/mcp

    daedalus
    A
    license
    A
    quality
    C
    maintenance
    MCP server that exposes a Telegram bot, enabling sending messages and retrieving updates through natural language.
    3
    1
    MIT

View all related MCP servers

Related MCP Connectors

  • mcp-glm

    MCP server for GLM chat completions using Zhipu AI models via AceDataCloud

  • mcp-aichat

    MCP server for AI dialogue using various LLM models via AceDataCloud

  • mcp-fish

    MCP server exposing the AceDataCloud Fish Audio API (text-to-speech with voice conditioning)

View all MCP Connectors

Latest Blog Posts

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