MCP 服务器

NapCat MCP Server

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

README

NapCat MCP Server

封装 NapCat 所有 HTTP API 的 MCP 服务器，支持 HTTP 和 WebSocket 双模式。

基于 napcat-group-info-mcp 扩展，新增消息发送、群管理、好友管理、系统管理等全量 API。

功能特性

📋 群聊信息获取（只读）
👥 群成员信息获取（只读）
📁 群文件管理（读写）
💬 消息发送与管理
📢 群公告管理
⭐ 群精华消息管理
👤 好友/用户管理
🔧 群管理操作（踢人、禁言、管理员等）
🖥️ 系统管理（登录信息、状态等）
🎨 Napcat 扩展功能（OCR、图片、语音等）
🔒 支持群号访问限制
🔐 支持只读模式
🌐 支持 HTTP 和 WebSocket 双模式

安装

git clone https://github.com/1021143806/napcat_mcp.git
cd napcat_mcp
pip install -e .

配置

在 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "napcat-mcp": {
      "command": "python",
      "args": ["path/to/run_direct.py"],
      "env": {
        "NAPCAT_HOST": "http://localhost:3000",
        "NAPCAT_TOKEN": "your_token_here",
        "ALLOWED_GROUPS": "",
        "READONLY_MODE": "false"
      }
    }
  }
}

环境变量

变量	说明	默认值
`NAPCAT_HOST`	NapCat 服务器地址	`http://localhost:3000`
`NAPCAT_TOKEN`	NapCat 访问令牌	空
`ALLOWED_GROUPS`	允许访问的群号（逗号分隔），留空=全部	空
`READONLY_MODE`	只读模式（true/false）	`false`

连接模式

根据 NAPCAT_HOST 前缀自动选择：

http:// 或 https:// → HTTP 模式
ws:// 或 wss:// → WebSocket 模式

安全特性

群号访问限制

ALLOWED_GROUPS=                    # 允许所有群
ALLOWED_GROUPS=628101497           # 只允许单个群
ALLOWED_GROUPS=628101497,123456789 # 允许多个群

只读模式

READONLY_MODE=true                 # 禁用所有写入操作

可用工具（55 个）

群聊信息（16 个）

get_group_info get_group_info_ex get_group_list get_group_honor_info get_group_at_all_remain get_group_member_list get_group_member_info get_group_root_files get_group_files_by_folder get_group_file_system_info get_group_file_url get_group_msg_history get_group_announcement_list get_essence_msg_list get_group_system_msg get_group_ignore_add_request

消息发送与管理（8 个）

send_msg send_group_msg send_private_msg delete_msg get_msg get_forward_msg send_group_forward_msg mark_msg_as_read

群管理（13 个）

set_group_kick set_group_ban set_group_whole_ban set_group_admin set_group_card set_group_name set_group_leave set_group_special_title set_group_add_request upload_group_file delete_group_file send_group_notice set_essence_msg delete_essence_msg

好友/用户（5 个）

get_friend_list get_stranger_info get_friend_msg_history send_like set_friend_add_request

系统管理（6 个）

get_login_info get_status get_version_info get_cookies get_csrf_token get_credentials

Napcat 扩展（7 个）

ocr_image get_image get_record can_send_image can_send_record get_online_client set_qq_profile

NapCat 配置

确保 NapCat 的 OneBot11 配置中启用了 HTTP 服务器：

{
  "network": {
    "httpServers": [{
      "enable": true,
      "name": "napcat mcp",
      "host": "127.0.0.1",
      "port": 3000,
      "enableCors": true,
      "enableWebsocket": true,
      "messagePostFormat": "array",
      "token": "your_token_here",
      "debug": false
    }]
  }
}