<center align="center" style="text-align: center;justify-content:center;">
<div align="center" style="text-align: center;justify-content:center;">
<h1 align="center" style="text-align: center;justify-content:center;">

Transmission MCP server

<img style="justify-content:center;text-align: center;width: 95px; height: auto;" width="793" height="411" alt="image" src="https://github.com/user-attachments/assets/abed1a04-d69b-4ab4-a490-d606064df72d" />
<img style="justify-content:center;text-align: center;width: 49px; height: auto;" alt="Transmission" src="public/logo.png" />

</h1>


![Version](https://img.shields.io/badge/version-1.0.0-blue.svg?style=for-the-badge) ![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white) ![Transmission](https://img.shields.io/badge/Transmission-D9291C?style=for-the-badge&logo=transmission&logoColor=white) ![Coverage](https://img.shields.io/badge/RPC_coverage-24%2F24-brightgreen?style=for-the-badge)

</div>
</center>

<hr>

Drive a Transmission daemon from Claude.ai and Claude Code. Every method in the RPC specification is a tool, with every mutator `torrent-set` accepts and every field `torrent-get` returns.

<hr>

> [!WARNING]
> Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. See [DISCLAIMER.md](DISCLAIMER.md).

## Why not the other options

* Existing Transmission MCP servers cover roughly 19 of the 24 methods, and all of them hard-code one protocol generation
* Transmission 4.1 renamed every RPC string to snake_case; Transmission 3 speaks only the old kebab-case names. This client probes once and then speaks whichever the daemon understands, so it works against both without configuration

## Coverage

| Group | Methods | Covered |
| --- | --- | --- |
| Torrent actions | 5 | 5 |
| Torrent accessor and mutator | 2 | 2 |
| Adding, removing, moving, renaming | 4 | 4 |
| Session | 4 | 4 |
| Queue | 4 | 4 |
| Blocklist, port test, free space | 3 | 3 |
| Bandwidth groups | 2 | 2 |

A test asserts every method in the spec is reachable from a tool.

## Tools

### Reading

| Tool | What you get |
| --- | --- |
| `list_torrents` | Every torrent with state, progress, speeds and a readable status name |
| `get_torrent` | One torrent in full: files, peers, trackers, tracker stats |
| `list_torrent_fields` | The field names `list_torrents` accepts |
| `get_session` | Every session setting and the daemon version |
| `get_session_stats` | Transfer totals, active counts, current speeds |
| `get_free_space` | Free space in a directory the daemon can see |
| `test_port` | Whether the peer port is reachable from outside |
| `get_bandwidth_groups` | Bandwidth groups and their limits |

### Torrents

| Tool | What it does |
| --- | --- |
| `add_torrent` | Add from a magnet link, URL, local .torrent file or base64 metainfo |
| `remove_torrent` | Remove torrents, optionally deleting the data |
| `start_torrents` | Start, respecting the queue |
| `start_torrents_now` | Start immediately, jumping the queue |
| `stop_torrents` | Stop |
| `verify_torrents` | Re-check data against its hashes |
| `reannounce_torrents` | Ask trackers for more peers now |
| `set_torrent` | Every per-torrent setting: limits, labels, file priorities, trackers, seeding rules |
| `move_torrent_data` | Move the data, or record where you already moved it |
| `rename_torrent_path` | Rename a file or directory inside a torrent |

### Queue and session

| Tool | What it does |
| --- | --- |
| `queue_move_top` | To the front of the queue |
| `queue_move_up` | One place up |
| `queue_move_down` | One place down |
| `queue_move_bottom` | To the back |
| `set_session` | Change any session setting |
| `set_bandwidth_group` | Create or change a bandwidth group |
| `update_blocklist` | Fetch a fresh blocklist |
| `shutdown_daemon` | Stop the daemon |

## Setup

```bash
git clone https://github.com/rollecode/transmission-mcp.git
cd transmission-mcp
uv venv && uv pip install -e .
```

```bash
export TRANSMISSION_URL=http://127.0.0.1:9091/transmission/rpc
export TRANSMISSION_USERNAME=...   # only if rpc-authentication-required is on
export TRANSMISSION_PASSWORD=...
```

The URL defaults to `http://127.0.0.1:9091/transmission/rpc`. A `.env` in the working directory works too.

### Claude Code

```bash
claude mcp add transmission -- /path/to/transmission-mcp/.venv/bin/transmission-mcp
```

## Ids

Anywhere a tool takes `ids`, it accepts torrent numbers, hash strings, or the literal `recently-active`. Omitting them means every torrent, which is why `remove_torrent` requires them.

## Hosting it

Running it over HTTP puts it in reach of Claude.ai as a custom connector, and of Claude Code on other machines. Three tiers, the same shape the other servers in this family use:

| Tier | Port | What it does |
| --- | --- | --- |
| `transmission-mcp` | 8510 | The server. No login of its own, never exposed |
| nginx | 8511 | Front door, behind a Cloudflare Tunnel |
| `auth-server.js` | 8512 | OAuth 2.1 sign-in, or a fixed bearer token |

```bash
npm install
node set-password.js 'a password for the sign-in page'
printf 'TRANSMISSION_URL=...\n' > ~/.config/transmission-mcp/env
chmod 600 ~/.config/transmission-mcp/env
```

Copy `systemd/*.service` into `/etc/systemd/system/`, replacing `YOUR_USER` and the `ISSUER` hostname, then:

```bash
sudo systemctl enable --now transmission-mcp transmission-mcp-auth
```

Point `nginx/transmission-mcp.conf` at your own hostname and send the tunnel at `127.0.0.1:8511`.

Environment the server itself reads: `TRANSMISSION_URL, TRANSMISSION_USERNAME, TRANSMISSION_PASSWORD`. The sign-in page carries the Transmission mark and accent colour, set through `APP_NAME`, `APP_ACCENT` and `APP_BLURB` in the auth unit.

### Claude.ai

Settings, Connectors, Add custom connector, URL `https://transmission-mcp.your-domain/mcp`, client ID and secret blank. The sign-in page asks for the password set above. Connectors belong to the account, so adding it once covers mobile too.

## Development

```bash
uv pip install -e . pytest ruff
.venv/bin/python -m pytest tests
.venv/bin/ruff check .
```