qui-mcp

Part of the arr-mcps collection. MCP server exposing qui's JSON REST API as tools for monitoring and managing qBittorrent instances, torrents, automations, cross-seeding, RSS, backups, and related services.

Built with FastMCP. The initial release mirrors the full 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

Related MCP server: rtorrent-mcp

Configuration

Create API keys in qui under Settings -> API Keys. The server never logs the key and sends no authentication header when it is unset.

Tools

12 resource-scoped tools, each covering multiple qui JSON endpoints (214 total) 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 application metadata. Call a tool with operation set to one of its listed routes and an arguments object matching that route's parameters — the tool's own description (visible to your MCP client) lists every route and its method + path. This keeps the full REST surface available while costing a fraction of the context budget of registering all 214 routes as separate tools.

Streaming endpoints and binary downloads are intentionally omitted because MCP tool results are structured JSON values. Session-creation endpoints (/auth/setup, /auth/login, and /auth/logout) are also omitted; use qui's web UI for those flows.

Every tool accepts operation (the route name, e.g. qui_list_torrents) plus one 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 in arguments.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 require QUI_URL and can be run with make test-integration.

The release workflow builds a wheel and source distribution when a v* tag is pushed. Start at version 0.0.0; use make bump-patch, commit, tag, and push for the first release.