home / mcp / qbit mcp server

Qbit MCP Server

Provides search, download, and management of torrents via qBittorrent Web API.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jabberjabberjabber-qbit-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "qbittorrent-api",
        "--with",
        "python-dotenv",
        "fastmcp",
        "run",
        "C:\\directy\\to\\qbit-mcp\\main.py"
      ],
      "env": {
        "QBITTORRENT_HOST": "http://localhost:8080",
        "QBITTORRENT_PASSWORD": "your_password",
        "QBITTORRENT_USERNAME": "admin"
      }
    }
  }
}

This MCP server lets you search qBittorrent using its built‑in search plugins, add torrents by URL or magnet link, manage existing torrents, and view available search plugins by connecting to qBittorrent’s Web API through a lightweight MCP interface.

How to use

Connect your MCP client to the qbit-mcp server you run locally or remotely. Once connected, you can search for torrents using the integrated search plugins, download torrents by URL or magnet link, retrieve information about current torrents, pause or resume downloads, and delete torrents. You can also list the available search plugins to tailor your searches. Use these tools to automate common torrent tasks through your MCP client without manually opening qBittorrent.

How to install

Prerequisites so you can run the server.

git clone <repository-url>
cd qbit-mcp

Install the MCP runtime and dependencies.

pip install uv

Configure the environment with your qBittorrent credentials.

cp .env.example .env

Edit `.env` with your qBittorrent credentials:
```
QBITTORRENT_HOST=http://localhost:8080
QBITTORRENT_USERNAME=admin
QBITTORRENT_PASSWORD=your_password

Additional notes

The server exposes a set of tools for practical torrent management. You will run the MCP server via an STDIO configuration using uv, with a command that starts the server and points to your main script. This setup enables you to control qBittorrent directly from your MCP client.

Troubleshooting

Connection issues: Ensure the qBittorrent Web UI is enabled and running, and verify that host, port, username, and password are correct. Check for firewall blocks if the connection fails.

Search not working: Install and enable the desired search plugins in qBittorrent's Search Engine. Some plugins may require updates.

Authentication failed: Double‑check the credentials in the environment file. Default credentials are often admin/adminadmin, but you should use the values you configured in the qBittorrent Web UI.

Available tools

search_torrents

Search for torrents using qBittorrent's search plugins with optional plugin filtering and category filtering.

download_torrent

Add a torrent by URL or magnet link, with optional save path, category, tags, and paused start option.

get_torrent_info

Retrieve information about current torrents, optionally filtering by a specific torrent hash.

list_search_plugins

List all available search plugins installed in qBittorrent.

pause_torrent

Pause an active torrent by its hash.

resume_torrent

Resume a paused torrent by its hash.

delete_torrent

Remove a torrent by hash and optionally delete the downloaded files.