Python API Wrapper & MCP Server for Transmission

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
Setup
Usage
Contributing
- Development
Changelog
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. (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.

Python API Wrapper & MCP Server for Transmission

Features
Setup
Usage
Contributing
- Development
Changelog
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. (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

Python API Wrapper & MCP Server for Transmission

Table of Contents

Features

Setup

Prerequisites

Configuration

Installation

Install from PyPI (Recommended)

For Local Development

For Docker

Usage

As Python API Wrapper

As MCP Server

Via MCP Clients

Example with Windsurf

Changelog

Contributing

License

Python API Wrapper & MCP Server for Transmission

Table of Contents

Features

Setup

Prerequisites

Configuration

Installation

Install from PyPI (Recommended)

For Local Development

For Docker

Usage

As Python API Wrapper

As MCP Server

Via MCP Clients

Example with Windsurf

Changelog

Contributing

License