# Python API Wrapper & MCP Server for Transmission
[](https://docs.astral.sh/uv/getting-started/installation/)
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/transmission-mcp)
[](https://github.com/philogicae/transmission-mcp/actions)
[](https://opensource.org/licenses/MIT)
[](https://deepwiki.com/philogicae/transmission-mcp)
This repository provides a Python API wrapper and an MCP (Model Context Protocol) server for the [Transmission](https://transmissionbt.com/) torrent client using the [transmission-rpc](https://github.com/Trim21/transmission-rpc) library. It allows for easy integration into other applications or services.
<a href="https://glama.ai/mcp/servers/@philogicae/transmission-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@philogicae/transmission-mcp/badge?cache-control=no-cache" alt="Transmission MCP server" />
</a>
## Table of Contents
- [Features](#features)
- [Setup](#setup)
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
- [Installation](#installation)
- [Install from PyPI (Recommended)](#install-from-pypi-recommended)
- [For Local Development](#for-local-development)
- [For Docker](#for-docker)
- [Usage](#usage)
- [As Python API Wrapper](#as-python-api-wrapper)
- [As MCP Server](#as-mcp-server)
- [Via MCP Clients](#via-mcp-clients)
- [Example with Windsurf](#example-with-windsurf)
- [Contributing](#contributing)
- [Development](#development)
- [Changelog](#changelog)
- [License](#license)
## Features
- API wrapper for the `Transmission` torrent client using the official `transmission-rpc` library.
- MCP server interface for standardized communication (stdio, sse, streamable-http).
- Tools:
- `get_session`: Get Transmission session configuration and version info.
- `get_session_stats`: Get session statistics (speeds, torrent counts, cumulative stats).
- `free_space`: Get free disk space in bytes at the specified path.
- `list_torrents`: List all torrents and their details.
- `get_torrent_details`: Get detailed information about a specific torrent.
- `get_torrent_stats`: Get stats/status of a specific torrent.
- `get_recently_active`: Get recently active torrents and IDs of recently removed ones.
- `add_torrent`: Download a torrent from magnet link, HTTP URL, or local file.
- `download_torrent`: Download a torrent from a magnet link, HTTP URL, or local file.
- `start_torrent`: Start (resume) a torrent.
- `stop_torrent`: Stop (pause) a torrent.
- `pause_torrent`: Pause a torrent.
- `verify_torrent`: Verify torrent data integrity.
- `reannounce_torrent`: Reannounce torrent to trackers.
- `move_torrent`: Move torrent data to a new location.
- `set_torrent_labels`: Set labels for a torrent.
- `remove_torrent`: Remove a torrent (optionally delete data).
- `delete_torrent`: Delete a torrent and its files.
- `forget_torrent`: Forget a torrent, keeping the files.
## Setup
### Prerequisites
- An running instance of [Transmission](https://transmissionbt.com/). (Included in docker compose)
- Python 3.10+ (required for PyPI install).
- [`uv`](https://github.com/astral-sh/uv) (for local development)
### Configuration
This application requires the URL of your `Transmission` instance.
**Set Environment Variable**: Copy `.env.example` to `.env` in your project's root directory and edit it with your settings. The application will automatically load variables from `.env`:
- MCP Server:
- `TRANSMISSION_URL`: The URL of the Transmission instance (Default: `http://localhost:9091`).
- `TRANSMISSION_USER`: The username for Transmission authentication (optional).
- `TRANSMISSION_PASS`: The password for Transmission authentication (optional).
- Transmission Instance (for docker-compose setup):
- `TRANSMISSION_DOWNLOAD_DIR`: The download directory for torrents (e.g., `/downloads`).
- `TRANSMISSION_WATCH_DIR`: The watch directory for torrent files (e.g., `/watch`).
- `TRANSMISSION_RPC_URL`: The RPC URL for the Transmission API (e.g., `http://localhost:9091/transmission/rpc`).
- `TRANSMISSION_PEER_PORT`: The peer port for BitTorrent connections (e.g., `51413`).
- `TRANSMISSION_SPEED_LIMIT_DOWN`: Download speed limit in KB/s (e.g., `100`).
- `TRANSMISSION_SPEED_LIMIT_UP`: Upload speed limit in KB/s (e.g., `100`).
- Check [Transmission](https://transmissionbt.com/) for other variables and more information.
### Installation
Choose one of the following installation methods.
#### Install from PyPI (Recommended)
This method is best for using the package as a library or running the server without modifying the code.
1. Install the package from PyPI:
```bash
pip install transmission-mcp
```
2. Create a `.env` file in the directory where you'll run the application and add your `Transmission` URL:
```env
TRANSMISSION_URL=http://localhost:9091
```
3. Run the MCP server (default: stdio):
```bash
python -m transmission_client
```
#### For Local Development
This method is for contributors who want to modify the source code.
Using [`uv`](https://github.com/astral-sh/uv):
1. Clone the repository:
```bash
git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp
```
2. Install dependencies using `uv`:
```bash
uv sync --locked
```
3. Create your configuration file by copying the example and add your settings:
```bash
cp .env.example .env
```
4. Run the MCP server (default: stdio):
```bash
uv run -m transmission_client
```
#### For Docker
This method uses Docker to run the server in a container.
compose.yaml includes [Transmission](https://transmissionbt.com/) torrent client.
1. Clone the repository (if you haven't already):
```bash
git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp
```
2. Create your configuration file by copying the example and add your settings:
```bash
cp .env.example .env
```
3. Build and run the container using Docker Compose (default port: 8000):
```bash
docker compose up --build -d
```
4. Access container logs:
```bash
docker logs transmission-mcp -f
```
## Usage
### As Python API Wrapper
```python
import asyncio
from transmission_client import TransmissionClient
async def main():
# Initialize client (reads TRANSMISSION_URL, TRANSMISSION_USER, and TRANSMISSION_PASS from env)
client = TransmissionClient()
# Use as context manager for automatic cleanup
async with TransmissionClient() as client:
# Get session info
session = await client.get_session()
print(f"Transmission version: {session['version']}")
# Get session statistics
stats = await client.get_session_stats()
print(f"Download speed: {stats['downloadSpeed']} bytes/s")
# Check free space
free_space = await client.free_space("/downloads")
print(f"Free space: {free_space} bytes")
# List all torrents
torrents = await client.list_torrents()
# Add a torrent
await client.add_torrent("magnet:?xt=urn:btih:...")
# Get torrent details
details = await client.get_torrent("1") # Use ID or hash
# Control torrents
await client.stop_torrent("1") # Pause
await client.start_torrent("1") # Resume
# Verify torrent data
await client.verify_torrent("1")
# Move torrent data
await client.move_torrent("1", "/new/location", move=True)
# Set torrent labels
await client.set_torrent_labels("1", ["movies", "4k"])
# Remove torrent (keep files)
await client.remove_torrent("1", delete_data=False)
# Delete torrent and files
await client.remove_torrent("1", delete_data=True)
if __name__ == "__main__":
asyncio.run(main())
```
### As MCP Server
```python
from transmission_client import TransmissionMCP
TransmissionMCP.run(transport="sse") # 'stdio', 'sse', or 'streamable-http'
```
### Via MCP Clients
Usable with any MCP-compatible client. Available tools:
- `get_session`: Get Transmission session configuration and version info.
- `get_session_stats`: Get session statistics (speeds, torrent counts, cumulative stats).
- `free_space`: Get free disk space in bytes at the specified path.
- `list_torrents`: List all torrents and their details.
- `get_torrent_details`: Get details of a specific torrent by ID or hash.
- `get_torrent_stats`: Get stats/status of a specific torrent by ID or hash.
- `get_recently_active`: Get recently active torrents and IDs of recently removed ones.
- `add_torrent`: Add a torrent from magnet link, HTTP URL, or local file path.
- `download_torrent`: Download a torrent via magnet link, HTTP URL, or local file.
- `start_torrent`: Start (resume) a torrent by ID or hash.
- `stop_torrent`: Stop (pause) a torrent by ID or hash.
- `pause_torrent`: Pause a torrent by ID or hash.
- `verify_torrent`: Verify torrent data integrity by ID or hash.
- `reannounce_torrent`: Reannounce torrent to trackers by ID or hash.
- `move_torrent`: Move torrent data to a new location by ID or hash.
- `set_torrent_labels`: Set labels for a torrent by ID or hash.
- `remove_torrent`: Remove a torrent (optionally delete data) by ID or hash.
- `delete_torrent`: Delete a torrent and its files by ID or hash.
- `forget_torrent`: Forget a torrent, keeping the files, by ID or hash.
#### Example with Windsurf
Configuration:
```json
{
"mcpServers": {
...
# with stdio (only requires uv)
"transmission-mcp": {
"command": "uvx",
"args": [ "transmission-mcp" ],
"env": {
"TRANSMISSION_URL": "http://localhost:9091", # (Optional) Default Transmission instance URL
"TRANSMISSION_USER": "username", # (Optional) Transmission username
"TRANSMISSION_PASS": "password" # (Optional) Transmission password
}
},
# with docker (only requires docker)
"transmission-mcp": {
"command": "docker",
"args": [ "run", "-i", "-p", "8000:8000", "-e", "TRANSMISSION_URL=http://localhost:9091", "-e", "TRANSMISSION_USER=username", "-e", "TRANSMISSION_PASS=password", "philogicae/transmission-mcp:latest", "transmission-mcp" ]
},
# with sse transport (requires installation)
"transmission-mcp": {
"serverUrl": "http://127.0.0.1:8000/sse"
},
# with streamable-http transport (requires installation)
"transmission-mcp": {
"serverUrl": "http://127.0.0.1:8000/mcp"
},
...
}
}
```
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this project.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
