Amadeus-QQ-MCP Server

You can run an MCP server that connects NapCatQQ to an AI client, enabling you to send and receive QQ messages in group chats and direct messages with automated, natural-feeling pacing and reliable WebSocket updates.

How to use

You will run the MCP server locally and connect it to NapCatQQ via HTTP and WebSocket channels. Your AI client can send messages to QQ targets and receive responses through the MCP, which handles message segmentation, typing delay simulation, and rate limiting. Configure groups and friends to listen to, then start the server to begin real-time message handling. Use the MCP client tools to check status, fetch context, and send messages.

How to install

Prerequisites you need before starting are Docker, Python 3.11 or newer, and uv.

# 1. Install Docker and NapCat

# macOS — install Docker Desktop
brew install --cask docker

# Ubuntu
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # run docker without sudo
# Re-login to apply group changes

# 2. Install NapCat

# The project uses NapCatQQ via a Docker image. The provided docker-compose.yml is ready to pull the image automatically on first run.

Start NapCat and then launch the MCP server using uv. The first time you start NapCat you will need to scan a login QR code. After logging in, you can lock in your QQ account for auto-login to avoid rescanning after restarts.

# 1. Start NapCat in detached mode

docker compose up -d

# 2. Start MCP server with minimal settings

uv run qq-agent-mcp --qq 你的QQ号

If you need to connect to NapCat with specific NapCat container settings (for example on an Ubuntu server with matching UID/GID), you can adjust the NapCat startup as shown:

# On Ubuntu, ensure UID/GID match the host user
NAPCAT_UID=1000 NAPCAT_GID=1000 docker compose up -d

To tailor the MCP server to your environment, you can specify the QQ account and target groups/friends explicitly when starting the server. The full command includes NapCat host/port, WebSocket port, and optional buffers and log level:

uv run qq-agent-mcp --qq 你的QQ号 \
  --napcat-host 127.0.0.1 \
  --napcat-port 3000 \
  --ws-port 3001 \
  --groups 群号1,群号2 \
  --friends 好友QQ1 \
  --buffer-size 100 \
  --log-level info

Additional setup for MCP client interaction

From an AI client perspective, add an MCP connection that uses standard input/output transport and runs the qq-agent-mcp command with your QQ number and target groups. You can configure a local client to start the MCP server process and talk via JSON-RPC over stdio.

{
  "name": "QQ Agent",
  "transport": "stdio",
  "command": "uv",
  "args": [
    "run", "--directory", "/path/to/qq-mcp",
    "qq-agent-mcp",
    "--qq", "你的QQ号",
    "--groups", "群号1,群号2"
  ]
}

Notes on operation

You can adjust the listening scope by listing groups and friends. The MCP provides five tools to manage status checks, group lists, context retrieval, message sending with natural pacing, and manual context compression. Expect real-time message events via WebSocket and automatic reconnection if the connection drops.

Configuration and tools

Key MCP tools include: check_status for verifying login and buffer statistics, get_group_list for listing joined groups, get_recent_context to fetch recent messages with context, send_message for sending content with formatting and typing delays, and compress_context to summarize history.

Security and maintenance

Keep NapCat and the MCP server updated to receive the latest stability and feature improvements. Limit access to the NapCat host to trusted networks and use the WebSocket port alongside encryption if possible. Regularly review your group and friend whitelists to ensure only intended conversations are monitored.

Available tools

check_status

Check QQ login status, online status, and buffer statistics.

get_group_list

Retrieve the list of groups you have joined.

get_recent_context

Fetch recent message context with metadata such as is_self and is_at_me.

send_message

Send a message to a target, automatically segmenting the content and applying typing delays.

compress_context

Manually compress historical messages into a concise summary.