Skip to content
MCP server

qBittorrent

qBittorrent MCP server that diagnoses uploads and manages many instances

Runs locallyStatus and history
Pricing
Free
Platforms
CLI, self-hosted
Runs
Locally
Version
0.2.4
Listing updated
2 days ago

About qBittorrent

qBittorrent is a free MCP server for developer tools. It runs locally on your machine and is started by your AI client.

qb-mcp wraps the qBittorrent WebUI API v2 in eleven tools grouped by intent instead of mirroring all 80-plus endpoints, which its author argues would give a model too many tools to choose from. The standout is qb_diagnose, which checks tracker health, the listening port, speed limits and peer supply to explain why an instance is not uploading, and it knows that qBittorrent 5.x renamed some endpoints.

You can configure any number of instances, each with its own URL, credentials and timeout, so one agent can manage a home NAS and a remote seedbox. Responses are trimmed from 30-plus fields to 12 per torrent, every write reports before and after state, and deleting a torrent never deletes files unless delete_files is set. Tracker URLs are redacted unless requested, credentials stay on your machine and nothing is logged.

It installs from PyPI and supports stdio and HTTP. The README says it is unofficial.

Install

Run in a terminal

claude mcp add qb-mcp -- uvx qb-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "qb-mcp": {
      "command": "uvx",
      "args": [
        "qb-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "qb-mcp": {
      "command": "uvx",
      "args": [
        "qb-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "qb-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "qb-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "qb-mcp": {
      "command": "uvx",
      "args": [
        "qb-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "qb-mcp": {
      "command": "uvx",
      "args": [
        "qb-mcp"
      ]
    }
  }
}

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

qb_instances
Lists configured instances and whether each is reachable.
qb_overview
Shows global status for one or all instances.
qb_list
Lists torrents with filtering, sorting and a row limit.
qb_detail
Shows one torrent in depth, including tracker status.
qb_diagnose
Explains why an instance is or is not uploading.
qb_control
Pauses, resumes, reannounces or force-starts torrents.
qb_set_limit
Sets global or per-torrent speed limits.
qb_set_share
Sets ratio and seeding-time limits and the action on reaching them.

What it does

Diagnose uploads
Explains why an instance is or is not uploading in one call.
Multiple instances
Each instance has separate credentials, such as a NAS and a seedbox.
Trimmed responses
Returns 12 fields per torrent instead of 30-plus.
Before and after reports
Writes show what changed.
Safe deletes
Removing a torrent keeps its files unless opted in.
Version-aware calls
Handles endpoints renamed in qBittorrent 5.x.

Good for

  • Find out why a seedbox is not uploading
  • Pause or resume torrents by asking
  • Set speed limits or share ratios per torrent
  • Check several qBittorrent instances from one agent
  • List and sort torrents with a row limit

Pricing

Free

Free PyPI package

Prices change. Check pypi.org before you buy.

qBittorrent FAQ

Is it affiliated with qBittorrent?

No, the README says it is unofficial.

How do I install it?

pip install qb-mcp, then create .instances.json with your qBittorrent URL and credentials.

Will it delete my files?

Not by default; delete_files is opt-in.

Where do credentials go?

Literal values, environment variables or a file path in .instances.json, kept out of version control.

Is qBittorrent free?

Yes. qBittorrent is free to use.

How do I add qBittorrent to Claude Code?

Run this command in your terminal: claude mcp add qb-mcp -- uvx qb-mcp

What are the best alternatives to qBittorrent?

The closest alternatives to qBittorrent are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to qBittorrent

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools