NapCat MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NapCat MCP Server list 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.
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 server address |
|
| NapCat access token | Empty |
| Allowed group IDs (comma-separated), leave empty for all | Empty |
| Read-only mode (true/false) |
|
Connection Modes
Automatically selected based on the NAPCAT_HOST prefix:
http://orhttps://→ HTTP modews://orwss://→ 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
httpxasynchronous clientWebSocket mode uses
websocketslibraryUses Pydantic for parameter validation
License
AGPL-3.0
Available Tools
57 toolscan_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
Scored across 57 tools
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.
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.
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.
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
Related MCP Connectors
Read chats and members; send, edit and delete messages with a bot in Telegram.
Operate one Evolution API (WhatsApp) instance: chats, history, sending, groups, settings.
Summarize, search, and manage your own WhatsApp groups from any MCP client.
Discover MCP servers and A2A agents; verify, message, post, follow, react, and receive webhooks.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn 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.726MIT
- AlicenseBqualityCmaintenanceConnects QQ via NapCat OneBot v11 to an Astral Code app-server, exposing MCP tools for sending messages, files, images, and fetching conversation history.102Apache 2.0
- FlicenseAqualityBmaintenanceEnables 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-
- AlicenseAqualityCmaintenanceEnables 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.5MIT