Python API Wrapper & MCP Server for Transmission

Python PyPI Actions status License: MIT Ask DeepWiki

This repository provides a Python API wrapper and an MCP (Model Context Protocol) server for the Transmission torrent client using the transmission-rpc library. It allows for easy integration into other applications or services.

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. (Included in docker compose)
Python 3.10+ (required for PyPI install).
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 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.

Install the package from PyPI:

pip install transmission-mcp

Create a .env file in the directory where you'll run the application and add your Transmission URL:

TRANSMISSION_URL=http://localhost:9091

Run the MCP server (default: stdio):

python -m transmission_client

For Local Development

This method is for contributors who want to modify the source code. Using uv:

Clone the repository:

git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp

Install dependencies using uv:

uv sync --locked

Create your configuration file by copying the example and add your settings:

cp .env.example .env

Run the MCP server (default: stdio):

uv run -m transmission_client

For Docker

This method uses Docker to run the server in a container. compose.yaml includes Transmission torrent client.

Clone the repository (if you haven't already):

git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp

Create your configuration file by copying the example and add your settings:

cp .env.example .env

Build and run the container using Docker Compose (default port: 8000):

docker compose up --build -d

Access container logs:

docker logs transmission-mcp -f

Usage

As Python API Wrapper

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

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:

{
  "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 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 file for details.

transmission-mcp