137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
# Transmission MCP Server
|
|
|
|
A multi-instance Transmission BitTorrent client MCP server following the "Hybrid MCP Light" pattern.
|
|
|
|
## Features
|
|
|
|
- **Multi-instance support**: Connect to multiple Transmission daemons simultaneously
|
|
- **Default instance**: Configure a default instance for convenience
|
|
- **Full API coverage**: Pass-through tool for any Transmission RPC method
|
|
- **Embedded documentation**: API reference available as an MCP resource
|
|
|
|
## Quick Start
|
|
|
|
1. Copy the environment template:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Edit `.env` with your Transmission instances:
|
|
```bash
|
|
TRANSMISSION_INSTANCES='[
|
|
{"name": "home", "url": "http://localhost:9091", "username": "admin", "password": "secret"},
|
|
{"name": "seedbox", "url": "https://seedbox.example.com/transmission"}
|
|
]'
|
|
TRANSMISSION_DEFAULT_INSTANCE=home
|
|
```
|
|
|
|
3. Run with Docker:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
Or run directly:
|
|
```bash
|
|
pip install .
|
|
python server.py
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `TRANSMISSION_INSTANCES` | Yes | JSON array of instance configurations |
|
|
| `TRANSMISSION_DEFAULT_INSTANCE` | No | Name of the default instance |
|
|
| `HOST` | No | Server bind address (default: `0.0.0.0`) |
|
|
| `PORT` | No | Server port (default: `8000`) |
|
|
|
|
### Instance Configuration
|
|
|
|
Each instance in `TRANSMISSION_INSTANCES` supports:
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| `name` | Yes | Unique identifier for this instance |
|
|
| `url` | Yes | Full URL to Transmission RPC endpoint |
|
|
| `username` | No | Username for HTTP Basic Auth |
|
|
| `password` | No | Password for HTTP Basic Auth |
|
|
|
|
## MCP Tools
|
|
|
|
### `list_instances`
|
|
Returns all configured Transmission instances with connectivity status.
|
|
|
|
### `get_torrents`
|
|
Get torrent list with common fields for a specific instance.
|
|
|
|
**Parameters:**
|
|
- `instance` (optional): Instance name (uses default if not specified)
|
|
- `ids` (optional): Specific torrent IDs to fetch
|
|
|
|
### `get_session_stats`
|
|
Get session statistics including speeds and torrent counts.
|
|
|
|
**Parameters:**
|
|
- `instance` (optional): Instance name (uses default if not specified)
|
|
|
|
### `rpc_call`
|
|
Execute any Transmission RPC method directly.
|
|
|
|
**Parameters:**
|
|
- `method`: RPC method name (e.g., `torrent_get`, `session_set`)
|
|
- `params` (optional): JSON string of method parameters
|
|
- `instance` (optional): Instance name (uses default if not specified)
|
|
|
|
## MCP Resources
|
|
|
|
### `transmission://api-reference`
|
|
Embedded Transmission RPC API documentation for AI agent reference.
|
|
|
|
## Examples
|
|
|
|
### List all torrents on default instance
|
|
```json
|
|
{"tool": "get_torrents"}
|
|
```
|
|
|
|
### Get torrents from specific instance
|
|
```json
|
|
{"tool": "get_torrents", "arguments": {"instance": "seedbox"}}
|
|
```
|
|
|
|
### Add a torrent via pass-through
|
|
```json
|
|
{
|
|
"tool": "rpc_call",
|
|
"arguments": {
|
|
"method": "torrent_add",
|
|
"params": "{\"filename\": \"magnet:?xt=urn:btih:...\"}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pause all torrents
|
|
```json
|
|
{
|
|
"tool": "rpc_call",
|
|
"arguments": {
|
|
"method": "torrent_stop",
|
|
"params": "{}"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Health Check
|
|
|
|
The server exposes a `/health` endpoint for Docker health checks and monitoring.
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|