cronus42/transmission-mcp

Transmission MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Transmission BitTorrent client via its RPC API.

Features

The server provides the following tools:

Torrent Management

• add_torrent: Add new torrents by URL, magnet link, or base64-encoded .torrent file
• remove_torrent: Remove torrents with optional local data deletion
• start_torrent: Start/resume torrents by ID
• stop_torrent: Stop/pause torrents by ID
• get_torrent_info: Get detailed information about specific torrents
• search_torrents: Search torrents by name with optional status filtering

Configuration

• set_torrent_priority: Set download priority (high/normal/low) for individual torrents
• set_speed_limits: Set global download/upload speed limits

Monitoring

• get_session_stats: Get comprehensive Transmission session statistics

Resources

The server also provides these resources for browsing:

• transmission://session - Current session information
• transmission://torrents - List of all torrents
• transmission://stats - Session statistics

Installation

1. Clone this repository:

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

2. Run the setup script:

./setup.sh

3. Configure your Transmission server settings (optional):

cp .env.example .env
# Edit .env with your Transmission server details

4. Ensure your Transmission daemon is running and RPC is enabled.

Testing

Run the test script to verify connectivity:

python test-transmission.py

Usage with MCP Client

Warp Terminal Integration

1. Run the setup script:

./setup.sh

2. Configure Warp to use the MCP server:

warp mcp add-server --config mcp_config.json

Or manually start the server:

./start_transmission_server.sh

Claude Desktop Configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "transmission": {
      "command": "/path/to/transmission-mcp/start_transmission_server.sh",
      "env": {},
      "args": []
    }
  }
}

Example Commands

Once connected via an MCP client, you can use commands like:

• "Add this magnet link: magnet:?xt=urn:btih:..."
• "Show me all torrents that are currently downloading"
• "Stop torrent with ID 5"
• "Get detailed info for torrent 3"
• "Set global download limit to 500 KB/s"
• "Search for torrents containing 'ubuntu'"
• "Show transmission statistics"

Transmission Setup

Ensure your Transmission daemon has RPC enabled. In your Transmission settings:

1. Enable "Allow remote access"
2. Set RPC port (usually 9091)
3. Configure authentication if needed (the current implementation assumes no auth)
4. Ensure the RPC whitelist includes your client IP

For headless Transmission (transmission-daemon), edit /etc/transmission-daemon/settings.json:

{
    "rpc-enabled": true,
    "rpc-port": 9091,
    "rpc-whitelist-enabled": false,
    "rpc-authentication-required": false
}

Security Notes

• The current implementation assumes no RPC authentication is required
• For production use, consider implementing authentication
• Ensure proper network security (firewall rules, VPN, etc.)
• Configure the server connection using environment variables (.env file)

API Reference

The server handles Transmission RPC API calls including:

• Session management with CSRF protection (X-Transmission-Session-Id header)
• Automatic retry on 409 errors to fetch new session IDs
• JSON RPC over HTTP POST requests
• Comprehensive error handling and logging

Error Handling

The server includes robust error handling for:

• Network connectivity issues
• HTTP errors and status codes
• Transmission RPC errors
• Invalid torrent IDs or malformed requests
• Session ID management and CSRF protection