qui-mcp
Part of the arr-mcps collection.MCP server exposing qui's JSON REST API astools for monitoring and managing qBittorrent instances, torrents,automations, cross-seeding, RSS, backups, and related services.
Built with FastMCP. The initial release mirrors thefull JSON API route surface as one MCP tool per endpoint.
Install
uv tool install qui_mcp-*.whl
Register with Claude Code:
claude mcp add qui \
--env QUI_URL=https://your-qui-host \
--env QUI_API_KEY=<api-key> \
-- qui-mcp
From source:
uv sync
claude mcp add qui \
--env QUI_URL=https://your-qui-host \
--env QUI_API_KEY=<api-key> \
-- uv run --directory /path/to/qui-mcp qui-mcp
Configuration
| Env var | Required | Description |
|---|---|---|
QUI_URL |
yes | qui host, optionally including a reverse-proxy base path; /api is appended automatically |
QUI_API_KEY |
no | API key sent as X-API-Key; omit only when qui authentication is intentionally disabled |
Create API keys in qui under Settings -> API Keys. The server never logsthe key and sends no authentication header when it is unset.
Tools
12 resource-scoped tools, each covering multiple qui JSON endpoints (214total) via an operation parameter: instances, torrents, categories, tags,preferences, automations, RSS, backups, orphan scans, cross-seed, Torznab,ARR integrations, notifications, API-key management, logs, and applicationmetadata. Call a tool with operation set to one of its listed routes and anarguments object matching that route's parameters — the tool's owndescription (visible to your MCP client) lists every route and its method +path. This keeps the full REST surface available while costing a fraction ofthe context budget of registering all 214 routes as separate tools.
| Tool | Routes |
|---|---|
qui_system |
55 |
qui_cross_seed |
29 |
qui_torrents |
24 |
qui_torznab |
20 |
qui_instances |
17 |
qui_dir_scan |
15 |
qui_rss |
14 |
qui_automations |
12 |
qui_backups |
10 |
qui_categories_tags |
7 |
qui_orphan_scan |
7 |
qui_torrent_creator |
4 |
Streaming endpoints and binary downloads are intentionally omitted because MCPtool results are structured JSON values. Session-creation endpoints(/auth/setup, /auth/login, and /auth/logout) are also omitted; use qui'sweb UI for those flows.
Every tool accepts operation (the route name, e.g. qui_list_torrents) plusone optional arguments object:
{
"operation": "qui_list_torrents",
"arguments": {
"instanceID": 1,
"hash": "torrent-info-hash",
"params": {"filter": "downloading"},
"body": {"value": "request payload"}
}
}
Path variables use their documented names. Query values belong inarguments.params and JSON request payloads belong in arguments.body.
Development
make help
make sync
make test
make build
make test uses only httpx.MockTransport. Live smoke tests requireQUI_URL and can be run with make test-integration.
The release workflow builds a wheel and source distribution when a v* tag ispushed. Start at version 0.0.0; use make bump-patch, commit, tag, and pushfor the first release.
