qq-agent

qq-agent is a zero-dependency CLI, MCP stdio server, and Agent Skill for a real, logged-in QQ account. It talks to a local OneBot 11 HTTP endpoint, normally provided by NapCat, and keeps sending disabled by default.

This package publishes only the NapCat/OneBot route. The macOS Computer Use skill is a separate project and should remain the default QQ route on macOS. Do not automatically enable this route on macOS unless the user explicitly requests NapCat/OneBot.

What is included

The CLI and MCP server have no npm runtime dependencies. Node.js 22 or newer is required because the local archive uses node:sqlite.

Related MCP server: napcat-mcp

Route boundaries

Use this project when:

• The user explicitly wants the NapCat/OneBot route.

• The host is Linux, WSL, Docker, or a macOS setup where the user explicitly chose NapCat.

• A local qq CLI is useful to an Agent, script, or MCP client.

Do not use this project:

• As an automatic macOS fallback when the separate qq-desktop-messaging Computer Use skill is available.

• With a public HTTP endpoint or without a token.

• For bulk messaging, moderation, account impersonation, or unattended writes.

Prerequisites

1. NapCat is running and the QQ NT client is logged in.

2. NapCat has an enabled HTTP Server network configuration.

3. Keep the NapCat endpoint bound to localhost or another trusted network.

4. Node.js >=22.

This repository does not bundle NapCat, QQ, or a QQ client. Follow the NapCat project documentation for installation and upstream versions.

Install

From a checkout:

npm install -g .
qq version
qq doctor

For local development:

npm link
qq version
npm test

Configure

Environment variables are supported:

export QQ_ONEBOT_URL='http://127.0.0.1:3000'
export QQ_ONEBOT_TOKEN='replace-with-a-long-random-token'
qq doctor

Or create a protected config file from the example:

mkdir -p ~/.config/qq-agent
cp config.example.json ~/.config/qq-agent/config.json
chmod 600 ~/.config/qq-agent/config.json

The CLI checks $QQ_CONFIG, then ./.qq-agent.json, then ~/.config/qq-agent/config.json, then ~/.qq-agent.json. Environment values override file values.

allowSend defaults to false. The send command fails until it is explicitly enabled, and a dry run is always available:

qq send --session group:123456 --text 'hello' --dry-run

CLI

qq version
qq doctor
qq manifest
qq status
qq sessions --keyword 'team'
qq history --session group:123456 --limit 100 --format agent
qq context --session group:123456 --seq 9002 --window 10
qq forward --id 123456789
qq sync --session group:123456
qq search 'migration' --session group:123456
qq media --file pic_001.jpg --kind image
qq media --file voice.silk --kind record
qq files --session group:123456
qq files-url --session group:123456 --file-id f1
qq download --url 'https://example.invalid/file' --out ~/Downloads
qq send --session group:123456 --text 'hello' --dry-run

Session IDs are group:123456 or user:456. The CLI emits one JSON envelope on stdout for --format json|agent; diagnostics go to stderr. Exit codes are 0 success, 2 usage/config error, 3 not found, 4 ambiguous, and 5 upstream/protocol error.

Agent Skill

Install the Skill into an Agent skill directory:

mkdir -p ~/.codex/skills
cp -R skills/qq-live ~/.codex/skills/

For DeepSeek Harness, use the equivalent ~/.dsh/skills/ directory.

The Skill must not silently fall back to NapCat/OneBot on macOS. The user or runtime must explicitly select this route.

MCP server

Codex ~/.codex/config.toml:

[mcp_servers.qq]
type = "stdio"
command = "node"
args = ["<PATH_TO_QQ_AGENT>/mcp/server.mjs"]
env = { QQ_ONEBOT_URL = "http://127.0.0.1:3000", QQ_ONEBOT_TOKEN = "replace-with-token" }

The MCP server exposes read tools by default and delegates all execution to the CLI, so the CLI remains the single source of truth.

Security

• Keep the OneBot endpoint on localhost or a trusted private network.

• Use a long random token. Never commit it.

• Keep allowSend disabled unless the user explicitly requests write access.

• Run --dry-run first for any send and verify the resolved session ID.

• Do not upload chat archives, media, tokens, or SQLite files to third-party services.

• This is not an official Tencent API and third-party protocol implementations can change.

See SECURITY.md for deployment details and vulnerability reporting.

Testing

No QQ account is required for the test suite:

npm test

Or run either suite independently:

npm run test:cli
npm run test:mcp

The tests launch local mock OneBot endpoints on 127.0.0.1, exercise read paths, verify the send gate, and check MCP JSON-RPC framing.

Repository layout

bin/qq.mjs              CLI implementation
mcp/server.mjs          MCP stdio adapter
skills/qq-live/         Agent Skill
mock/                   Mock OneBot HTTP endpoint
test/                   CLI and MCP smoke tests
config.example.json      Safe default configuration

License

MIT. See LICENSE.