Skip to main content
Glama
NapCat MCP Server

NapCat MCP Server

by ptrel1

NapCat MCP Server

An MCP server that encapsulates all NapCat HTTP APIs, supporting both HTTP and WebSocket modes.

Based on the napcat-group-info-mcp extension, adding full API support for message sending, group management, friend management, system management, and more.

Features

  • 📋 Group chat information retrieval (read-only)

  • 👥 Group member information retrieval (read-only)

  • 📁 Group file management (read/write)

  • 💬 Message sending and management

  • 📢 Group announcement management

  • ⭐ Group essence message management

  • 👤 Friend/user management

  • 🔧 Group management operations (kick, ban, admin, etc.)

  • 🖥️ System management (login info, status, etc.)

  • 🎨 Napcat extended functions (OCR, images, voice, etc.)

  • 🔒 Supports group ID access restrictions

  • 🔐 Supports read-only mode

  • 🌐 Supports both HTTP and WebSocket modes

Related MCP server: astral-bridge

Installation

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

Configuration

Add to your MCP client configuration file:

{
  "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"
      }
    }
  }
}

Environment Variables

Variable

Description

Default Value

NAPCAT_HOST

NapCat server address

http://localhost:3000

NAPCAT_TOKEN

NapCat access token

Empty

ALLOWED_GROUPS

Allowed group IDs (comma-separated), leave empty for all

Empty

READONLY_MODE

Read-only mode (true/false)

false

Connection Modes

Automatically selected based on the NAPCAT_HOST prefix:

  • http:// or https:// → HTTP mode

  • ws:// or wss:// → WebSocket mode

Security Features

Group ID Access Restrictions

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

Read-only Mode

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

Available Tools (55)

Group Chat Information (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

Message Sending and Management (8)

send_msg send_group_msg send_private_msg delete_msg get_msg get_forward_msg send_group_forward_msg mark_msg_as_read

Group Management (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

Friend/User (5)

get_friend_list get_stranger_info get_friend_msg_history send_like set_friend_add_request

System Management (6)

get_login_info get_status get_version_info get_cookies get_csrf_token get_credentials

Napcat Extensions (7)

ocr_image get_image get_record can_send_image can_send_record get_online_client set_qq_profile

NapCat Configuration

Ensure that the HTTP server is enabled in NapCat's OneBot11 configuration:

{
  "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
    }]
  }
}

Technical Details

  • Based on the OneBot11 standard

  • Compatible with NapCat 4.9.91+

  • HTTP mode uses httpx asynchronous client

  • WebSocket mode uses websockets library

  • Uses Pydantic for parameter validation

License

AGPL-3.0

Available Tools

57 tools
can_send_imageB

Check if can send image

Inputs: no named parameters.

can_send_recordB

Check if can send voice record

Inputs: no named parameters.

delete_essence_msgC

Delete essence message

Inputs: message_id (required).

delete_group_fileC

Delete group file

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

delete_msgC

Recall message

Inputs: message_id (required).

get_cookiesD

Get cookies

Inputs: domain.

get_credentialsC

Get credentials

Inputs: domain.

get_csrf_tokenC

Get CSRF token

Inputs: no named parameters.

get_essence_msg_listC

Get group essence message list

Inputs: group_id (required).

get_forward_msgC

Get forward message

Inputs: message_id (required).

get_friend_listD

Get friend list

Inputs: no named parameters.

get_friend_msg_historyC

Get friend message history

Inputs: user_id (required), count, message_seq.

get_group_announcement_listC

Get group announcement list

Inputs: group_id (required).

get_group_at_all_remainB

Get remaining @all count for group

Inputs: group_id (required).

get_group_files_by_folderB

Get file list in specified group folder

Inputs: group_id (required), folder_id.

get_group_file_system_infoB

Get group file system information

Inputs: group_id (required).

get_group_file_urlC

Get group file download URL

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

get_group_honor_infoC

Get group honor information

Inputs: group_id (required), type.

get_group_ignore_add_requestC

Get group ignored join requests

Inputs: group_id (required).

get_group_infoC

Get group detailed information

Inputs: group_id (required).

get_group_info_exC

Get group detailed information (extended)

Inputs: group_id (required).

get_group_listB

Get list of all joined groups

Inputs: no named parameters.

get_group_member_infoB

Get specified group member detailed info

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

get_group_member_listD

Get group member list

Inputs: group_id (required).

get_group_msg_historyC

Get group message history with IDs and structured OneBot fields for pagination or follow-up actions

Inputs: group_id (required), count, message_seq.

get_group_root_filesB

Get group root directory file list

Inputs: group_id (required).

get_group_system_msgC

Get group system messages

Inputs: group_id (required).

get_imageC

Get image information

Inputs: file (required).

get_login_infoB

Get login account information

Inputs: no named parameters.

get_msgC

Get message details

Inputs: message_id (required).

get_online_clientB

Get online client list

Inputs: no named parameters.

get_recordC

Get voice record information

Inputs: file (required), out_format.

get_statusC

Get running status

Inputs: no named parameters.

get_stranger_infoC

Get stranger information

Inputs: user_id (required), no_cache.

get_version_infoC

Get version information

Inputs: no named parameters.

mark_msg_as_readC

Mark message as read

Inputs: message_id (required).

ocr_imageC

OCR image recognition

Inputs: image (required).

read_group_messagesA

Read recent group messages as a minimal human-readable timeline. Prefer this for understanding chat; use get_group_msg_history only when IDs, pagination, or raw segments are needed.

Inputs: group_id (required), count.

send_group_forward_msgC

Send group forward message

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

send_group_msgC

Send group message

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

send_group_noticeC

Send group announcement

Inputs: title (required), content (required), group_id (required).

send_likeD

Send like

Inputs: user_id (required), times.

send_msgC

Send message (generic)

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

send_private_msgC

Send private message

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

set_essence_msgD

Set essence message

Inputs: message_id (required).

set_friend_add_requestC

Handle friend request

Inputs: flag (required), remark, approve.

set_group_add_requestC

Handle group join request

Inputs: flag (required), reason, approve, sub_type.

set_group_adminB

Set group admin

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

set_group_banC

Mute group member

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

set_group_cardC

Set group member card

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

set_group_kickB

Kick member from group

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

set_group_leaveC

Leave or dismiss group

Inputs: group_id (required), is_dismiss.

set_group_nameC

Set group name

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

set_group_special_titleB

Set group special title

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

set_group_whole_banB

Mute all members in group

Inputs: group_id (required), enable.

set_qq_profileC

Set QQ profile

Inputs: sex, nickname, personal_note.

upload_group_fileC

Upload group file

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

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 57 tools

    Disambiguation3/5

    Most tools are distinct, but there is overlap: get_group_info and get_group_info_ex, get_group_msg_history and read_group_messages (though descriptions differentiate), and get_csrf_token/get_credentials/get_cookies are similar. These could cause confusion.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, e.g., get_group_list, send_msg, set_group_kick, delete_msg. No mixed conventions.

    Tool Count2/5

    With 57 tools, the server is heavily overloaded, especially for a single domain (QQ bot). Many are low-level APIs that could be consolidated; this exceeds typical well-scoped MCP servers.

    Completeness4/5

    The tool set covers most QQ group and friend operations including messaging, file management, announcements, and moderation. Minor gaps: no tool to get group member profile or send private files, but overall complete for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      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
      26
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Connects QQ via NapCat OneBot v11 to an Astral Code app-server, exposing MCP tools for sending messages, files, images, and fetching conversation history.
      10
      2
      Apache 2.0
    • F
      license
      A
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables interaction with QQ through official bot APIs or personal accounts bridged via NapCat/OneBot v11, including status checks, target listing, bounded context retrieval, and plain-text sending to allowlisted conversations.
      5
      MIT