# qBittorrent

> qBittorrent is a free MCP server for developer tools. qBittorrent MCP server that diagnoses uploads and manages many instances. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, self-hosted
- **Website:** https://pypi.org/project/qb-mcp/
- **Repository:** https://github.com/zxw060810/qb-mcp
- **MCP Registry name:** io.github.zxw060810/qb-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add qb-mcp -- uvx qb-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/qbittorrent
