Transmission Mcp

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 torrent client using the transmission-rpc library. It allows for easy integration into other applications or services.

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. (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.

1. Install the package from PyPI:

pip install transmission-mcp

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

TRANSMISSION_URL=http://localhost:9091

1. 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:

1. Clone the repository:

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

1. Install dependencies using uv:

uv sync --locked

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

cp .env.example .env

1. 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.

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

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

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

cp .env.example .env

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

docker compose up --build -d

1. 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](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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: philogicae
• Source: philogicae/transmission-mcp
• License: MIT
• Homepage: https://deepwiki.com/philogicae/transmission-mcp

Install and usage instructions live in the source repository linked above.