# qBittorrent MCP Server

An MCP server for controlling a qBittorrent instance through its WebUI API, using cookie-session auth. Covers torrents, categories, and transfer data.

## Requirements

- Node.js 20+
- A running qBittorrent WebUI

## Install

```bash
git clone https://github.com/mattmaas/qbittorrent-mcp.git
cd qbittorrent-mcp
npm install
npm start         # node server.mjs
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `QBITTORRENT_URL` | yes | Base URL of the WebUI, e.g. `http://localhost:8080` |
| `QBITTORRENT_USERNAME` | yes | WebUI login name |
| `QBITTORRENT_PASSWORD` | yes | WebUI password |

## MCP Client Configuration

Add this server to your MCP client's config:

```json
{
  "mcpServers": {
    "qbittorrent": {
      "command": "node",
      "args": ["<path>/qbittorrent-mcp/server.mjs"],
      "env": {
        "QBITTORRENT_URL": "http://localhost:8080",
        "QBITTORRENT_USERNAME": "admin",
        "QBITTORRENT_PASSWORD": "your-password"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `qbittorrent_get_torrents` | List torrents with status and stats |
| `qbittorrent_get_torrent_info` | Detailed properties for a torrent |
| `qbittorrent_add_torrent_magnet` | Add a torrent from a magnet link |
| `qbittorrent_pause_torrents` | Pause torrent(s) |
| `qbittorrent_resume_torrents` | Resume torrent(s) |
| `qbittorrent_delete_torrents` | Delete torrent(s) (optionally files) |
| `qbittorrent_get_transfer_info` | Global transfer statistics |
| `qbittorrent_set_speed_limits` | Set global download/upload limits |
| `qbittorrent_toggle_alt_speed` | Toggle alternative speed limits |
| `qbittorrent_get_categories` | List categories with save paths |
| `qbittorrent_set_torrent_category` | Assign a category to torrent(s) |
| `qbittorrent_recheck_torrents` | Force a hash recheck |
| `qbittorrent_get_app_version` | App and API version |
| `qbittorrent_get_preferences` | Application settings |

## Usage

Ask your agent, for example:

- "What's downloading right now?" → `qbittorrent_get_torrents(filter="downloading")`
- "Add this magnet and tag it 'linux'" → `qbittorrent_add_torrent_magnet(magnet="magnet:?...", tags="linux")`
- "Throttle uploads to 1 MB/s" → `qbittorrent_set_speed_limits(upload_limit=1048576)`

## License

MIT