RELATED 01
Backstage MCP Actions
OFFICIAL SERVERBackstage backend plugin that serves your portal's registered actions as MCP tools over HTTP
35kGitHub stars
95k/wknpm downloads
102popularity score
SnowLuma MCP
Browse SnowLuma's OneBot v11 action reference for QQ bots, and optionally call those actions
By SnowLuma TypeScript Local · stdio CommunicationDeveloper tools
85 popularity score ★ 3.8k ↓ 51k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
Claude CodeTerminal
claude mcp add snowluma -- npx -y @snowluma/mcpClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"snowluma": {
"command": "npx",
"args": [
"-y",
"@snowluma/mcp"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"snowluma": {
"command": "npx",
"args": [
"-y",
"@snowluma/mcp"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"snowluma": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@snowluma/mcp"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.snowluma]
command = "npx"
args = ["-y", "@snowluma/mcp"]Gemini CLITerminal
gemini mcp add --scope user snowluma npx -- -y @snowluma/mcpSettings 7
SNOWLUMA_MCP_ENDPOINT |
Optional: OneBot HTTP endpoint of a running SnowLuma, e.g. http://127.0.0.1:3000/. Unset means docs-only. |
|---|---|
SNOWLUMA_MCP_TOKEN |
Optional: Access token sent as a Bearer header, when the endpoint requires one. |
SNOWLUMA_MCP_MODE |
Optional: docs, read or write. Defaults to read with an endpoint, docs without; ignored without an endpoint. |
SNOWLUMA_MCP_TIMEOUT_MS |
Optional: Request timeout, and idle timeout for streams. Default 30000. |
SNOWLUMA_MCP_STREAM_DIR |
Optional: Folder for finished stream downloads. Default: a onebot-mcp-downloads folder in the system temp dir. |
SNOWLUMA_MCP_UPLOAD_ROOT |
Optional: Existing folder automatic uploads may read from; uploads are off when unset. |
SNOWLUMA_MCP_MAX_STREAM_BYTES |
Optional: Per-file download/upload cap in bytes, up to 4 GiB (the default). |
What it does
SnowLuma is a third-party runtime that turns a QQ client session into OneBot v11 actions and events. This package, @snowluma/mcp, is its MCP server. In its default mode it needs nothing else: it serves the OneBot action catalog that ships inside the package, so an assistant can list actions by category, search them, and fetch one action's parameters, constraints and JSON Schema without loading the whole reference. The full catalog is also offered as the resource snowluma://onebot/actions.
When SNOWLUMA_MCP_ENDPOINT points at the OneBot HTTP adapter of a running SnowLuma instance, the server can also call actions. In read mode (the default once an endpoint is set) query_action runs only actions the catalog marks read-only. In write mode invoke_action can run any catalog action, including sending messages, changing groups and the file stream actions that download to, or upload from, the machine the server runs on. Actions outside the catalog are refused by both tools.
The catalog is a snapshot taken when the package is built, so it matches the SnowLuma release it was published with (1.14.22 at the time of writing) rather than whatever instance you connect to. One detail the README leaves out: in server.ts, setting SNOWLUMA_MCP_MODE to read or write without an endpoint is ignored with a warning on stderr and the server stays docs-only.
What it needs
| Runtime | Node.js 22+ |
|---|
Node.js with npx. Docs mode needs nothing more. Execution needs a running SnowLuma instance (a QQ client plus the SnowLuma runtime, whose Lite build wants Node.js 22.13+) with its OneBot httpServer adapter enabled, and that endpoint's access token if it has one.
Limits
Speaks stdio only. Execution covers OneBot actions over HTTP; it does not receive events. Stream actions count as writes, so file downloads and uploads need write mode. At most four stream actions run at once; files are capped at 4 GiB each by default (SNOWLUMA_MCP_MAX_STREAM_BYTES), downloads share a quota of twice that cap, and finished downloads are never deleted by the server. Automatic upload is off unless SNOWLUMA_MCP_UPLOAD_ROOT is set. SnowLuma is not affiliated with Tencent/QQ, is offered for study and research only, and its makers tell users to follow the QQ user agreement.
Who it suits
Suits developers writing OneBot v11 bots against SnowLuma who want an assistant to look up action names and parameters; docs mode reads nothing outside the package and is low-stakes. Execution suits operators who already run SnowLuma and want an assistant to inspect or drive a QQ account, read mode first. Write mode lets the assistant send messages as that account, so pick it only with a client that asks before destructive calls. Not useful for other OneBot implementations' extras, or for anyone without a QQ bot setup.
Tools 6
list_actions- Lists catalog actions with category, summary, aliases and read-only flag, optionally for one category.
get_action- Returns the full documentation and input JSON Schema for one action, accepting aliases.
search_actions- Fuzzy-searches action names, summaries and aliases.
list_categories- Lists action categories with how many actions each holds.
query_action- Calls a read-only OneBot action on the configured endpoint; needs SNOWLUMA_MCP_ENDPOINT.
invoke_action- Calls any catalog action, including ones that send or change things and file streams; write mode only.