Transmission MCP

🚀 Transmission用Python APIラッパーとMCPサーバー

このリポジトリは、transmission-rpcライブラリを使用して、Transmissionトレントクライアント用のPython APIラッパーとMCP（Model Context Protocol）サーバーを提供します。他のアプリケーションやサービスへの簡単な統合を可能にします。

🚀 クイックスタート

このセクションでは、このプロジェクトの使用を始めるための基本的な手順を説明します。

✨ 主な機能

• 公式のtransmission-rpcライブラリを使用したTransmissionトレントクライアント用のAPIラッパー。
• 標準化された通信（stdio、sse、streamable-http）用のMCPサーバーインターフェイス。
• 以下のツールが利用可能です：
  • get_session：Transmissionのセッション設定とバージョン情報を取得します。
  • get_session_stats：セッションの統計情報（速度、トレント数、累積統計）を取得します。
  • free_space：指定されたパスの空きディスク容量をバイト単位で取得します。
  • list_torrents：すべてのトレントとその詳細をリストします。
  • get_torrent_details：特定のトレントの詳細情報を取得します。
  • get_torrent_stats：特定のトレントの統計情報/ステータスを取得します。
  • get_recently_active：最近アクティブなトレントと最近削除されたトレントのIDを取得します。
  • add_torrent：マグネットリンク、HTTP URL、またはローカルファイルからトレントをダウンロードします。
  • download_torrent：マグネットリンク、HTTP URL、またはローカルファイルからトレントをダウンロードします。
  • start_torrent：トレントを開始（再開）します。
  • stop_torrent：トレントを停止（一時停止）します。
  • pause_torrent：トレントを一時停止します。
  • verify_torrent：トレントデータの整合性を検証します。
  • reannounce_torrent：トラッカーにトレントを再アナウンスします。
  • move_torrent：トレントデータを新しい場所に移動します。
  • set_torrent_labels：トレントにラベルを設定します。
  • remove_torrent：トレントを削除します（オプションでデータを削除）。
  • delete_torrent：トレントとそのファイルを削除します。
  • forget_torrent：トレントを忘れ、ファイルを残します。

📦 インストール

前提条件

• Transmissionの実行インスタンス。（docker composeに含まれています）
• Python 3.10以上（PyPIインストールに必要）。
• uv（ローカル開発用）

設定

このアプリケーションには、TransmissionインスタンスのURLが必要です。

環境変数の設定：プロジェクトのルートディレクトリで.env.exampleを.envにコピーし、設定を編集してください。アプリケーションは自動的に.envから変数を読み込みます。

• MCPサーバー：
  • TRANSMISSION_URL：TransmissionインスタンスのURL（デフォルト：http://localhost:9091）。
  • TRANSMISSION_USER：Transmission認証用のユーザー名（オプション）。
  • TRANSMISSION_PASS：Transmission認証用のパスワード（オプション）。
• Transmissionインスタンス（docker-compose設定用）：
  • TRANSMISSION_DOWNLOAD_DIR：トレントのダウンロードディレクトリ（例：/downloads）。
  • TRANSMISSION_WATCH_DIR：トレントファイルのウォッチディレクトリ（例：/watch）。
  • TRANSMISSION_RPC_URL：Transmission APIのRPC URL（例：http://localhost:9091/transmission/rpc）。
  • TRANSMISSION_PEER_PORT：BitTorrent接続用のピアポート（例：51413）。
  • TRANSMISSION_SPEED_LIMIT_DOWN：ダウンロード速度制限（KB/s）（例：100）。
  • TRANSMISSION_SPEED_LIMIT_UP：アップロード速度制限（KB/s）（例：100）。
  • 他の変数や詳細情報については、Transmissionを確認してください。

インストール方法

以下のインストール方法から1つを選択してください。

PyPIからのインストール（推奨）

この方法は、パッケージをライブラリとして使用するか、コードを変更せずにサーバーを実行する場合に最適です。

1. PyPIからパッケージをインストールします：

pip install transmission-mcp

2. アプリケーションを実行するディレクトリに.envファイルを作成し、TransmissionのURLを追加します：

TRANSMISSION_URL=http://localhost:9091

3. MCPサーバーを実行します（デフォルト：stdio）：

python -m transmission_client

ローカル開発用

この方法は、ソースコードを変更したい貢献者向けです。 uvを使用します。

1. リポジトリをクローンします：

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

2. uvを使用して依存関係をインストールします：

uv sync --locked

3. 設定ファイルをコピーし、設定を追加します：

cp .env.example .env

4. MCPサーバーを実行します（デフォルト：stdio）：

uv run -m transmission_client

Dockerを使用する場合

この方法は、Dockerを使用してサーバーをコンテナ内で実行します。 compose.yamlにはTransmissionトレントクライアントが含まれています。

1. リポジトリをクローンします（まだクローンしていない場合）：

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

2. 設定ファイルをコピーし、設定を追加します：

cp .env.example .env

3. Docker Composeを使用してコンテナをビルドして実行します（デフォルトポート：8000）：

docker compose up --build -d

4. コンテナのログを確認します：

docker logs transmission-mcp -f

💻 使用例

Python APIラッパーとして

import asyncio
from transmission_client import TransmissionClient

async def main():
    # クライアントを初期化します（TRANSMISSION_URL、TRANSMISSION_USER、TRANSMISSION_PASSを環境変数から読み込みます）
    client = TransmissionClient()

    # 自動クリーンアップのためにコンテキストマネージャーとして使用します
    async with TransmissionClient() as client:
        # セッション情報を取得します
        session = await client.get_session()
        print(f"Transmission version: {session['version']}")

        # セッションの統計情報を取得します
        stats = await client.get_session_stats()
        print(f"Download speed: {stats['downloadSpeed']} bytes/s")

        # 空き容量を確認します
        free_space = await client.free_space("/downloads")
        print(f"Free space: {free_space} bytes")

    # すべてのトレントをリストします
    torrents = await client.list_torrents()

    # トレントを追加します
    await client.add_torrent("magnet:?xt=urn:btih:...")

    # トレントの詳細を取得します
    details = await client.get_torrent("1")  # IDまたはハッシュを使用

    # トレントを制御します
    await client.stop_torrent("1")  # 一時停止
    await client.start_torrent("1")  # 再開

    # トレントデータを検証します
    await client.verify_torrent("1")

    # トレントデータを移動します
    await client.move_torrent("1", "/new/location", move=True)

    # トレントにラベルを設定します
    await client.set_torrent_labels("1", ["movies", "4k"])

    # トレントを削除します（ファイルを残す）
    await client.remove_torrent("1", delete_data=False)

    # トレントとそのファイルを削除します
    await client.remove_torrent("1", delete_data=True)

if __name__ == "__main__":
    asyncio.run(main())

MCPサーバーとして

from transmission_client import TransmissionMCP

TransmissionMCP.run(transport="sse") # 'stdio', 'sse', or 'streamable-http'

MCPクライアントを介して

任意のMCP互換クライアントで使用可能です。利用可能なツールは以下の通りです：

• get_session：Transmissionのセッション設定とバージョン情報を取得します。
• get_session_stats：セッションの統計情報（速度、トレント数、累積統計）を取得します。
• free_space：指定されたパスの空きディスク容量をバイト単位で取得します。
• list_torrents：すべてのトレントとその詳細をリストします。
• get_torrent_details：IDまたはハッシュで特定のトレントの詳細を取得します。
• get_torrent_stats：IDまたはハッシュで特定のトレントの統計情報/ステータスを取得します。
• get_recently_active：最近アクティブなトレントと最近削除されたトレントのIDを取得します。
• add_torrent：マグネットリンク、HTTP URL、またはローカルファイルパスからトレントを追加します。
• download_torrent：マグネットリンク、HTTP URL、またはローカルファイルからトレントをダウンロードします。
• start_torrent：IDまたはハッシュでトレントを開始（再開）します。
• stop_torrent：IDまたはハッシュでトレントを停止（一時停止）します。
• pause_torrent：IDまたはハッシュでトレントを一時停止します。
• verify_torrent：IDまたはハッシュでトレントデータの整合性を検証します。
• reannounce_torrent：IDまたはハッシュでトラッカーにトレントを再アナウンスします。
• move_torrent：IDまたはハッシュでトレントデータを新しい場所に移動します。
• set_torrent_labels：IDまたはハッシュでトレントにラベルを設定します。
• remove_torrent：IDまたはハッシュでトレントを削除します（オプションでデータを削除）。
• delete_torrent：IDまたはハッシュでトレントとそのファイルを削除します。
• forget_torrent：IDまたはハッシュでトレントを忘れ、ファイルを残します。

Windsurfを使用した例

設定：

{
  "mcpServers": {
    ...
    # stdioを使用する場合（uvのみ必要）
    "transmission-mcp": {
      "command": "uvx",
      "args": [ "transmission-mcp" ],
      "env": {
        "TRANSMISSION_URL": "http://localhost:9091", # (Optional) デフォルトのTransmissionインスタンスURL
        "TRANSMISSION_USER": "username", # (Optional) Transmissionユーザー名
        "TRANSMISSION_PASS": "password" # (Optional) Transmissionパスワード
      }
    },
    # dockerを使用する場合（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" ]
    },
    # sseトランスポートを使用する場合（インストールが必要）
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # streamable-httpトランスポートを使用する場合（インストールが必要）
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp"
    },
    ...
  }
}

📚 ドキュメント

このプロジェクトの変更履歴については、CHANGELOG.mdを参照してください。

🔧 技術詳細

本プロジェクトでは、transmission-rpcライブラリを用いてTransmissionトレントクライアントのAPIをラップし、MCPサーバーを構築しています。Python 3.10以降を必要とし、環境変数を通じてTransmissionインスタンスの設定を行います。各種トレント操作の関数は非同期処理をサポートしており、asyncioを利用して効率的な実行が可能です。また、MCPサーバーはstdio、sse、streamable-httpといった異なるトランスポート方式をサポートしており、柔軟な通信が可能です。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSEファイルを参照してください。

🔗 貢献方法

貢献は大歓迎です！問題を開くか、プルリクエストを送信してください。