Rqbit MCP

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

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

📚 目次

• 主な機能
• セットアップ
  • 前提条件
  • 設定
  • インストール
    • PyPIからインストール（推奨）
    • ローカル開発用
    • Docker用
• 環境変数
• 使用例
  • Python APIラッパーとして
  • MCPサーバーとして
  • MCPクライアント経由
    • Windsurfを使用した例
• コントリビュート
• 変更履歴
• ライセンス

✨ 主な機能

• rqbitトレントクライアント用のAPIラッパー。
• 標準化された通信（stdio、sse、streamable-http）用のMCPサーバーインターフェイス。
• ツール:
  • list_torrents: すべてのトレントとその詳細をリスト表示します。
  • download_torrent: マグネットリンクまたはファイルからトレントをダウンロードします。
  • get_torrent_details: 特定のトレントの詳細情報を取得します。
  • get_torrent_stats: 特定のトレントの統計情報/ステータスを取得します。
  • pause_torrent: トレントを一時停止します。
  • start_torrent: トレントを開始します。
  • forget_torrent: トレントを忘れ、ファイルを保持します。
  • delete_torrent: トレントとそのファイルを削除します。

📦 インストール

前提条件

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

設定

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

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

• MCPサーバー:
  • RQBIT_URL: rqbitインスタンスのURL（デフォルト: http://localhost:3030）。
  • RQBIT_HTTP_BASIC_AUTH_USERPASS: rqbitインスタンスで設定されている場合。
• Rqbitインスタンス:
  • RQBIT_HTTP_BASIC_AUTH_USERPASS: 基本認証のユーザー名とパスワード。username:passwordの形式。
  • RQBIT_HTTP_API_LISTEN_ADDR: HTTP APIのリッスンアドレス（例: 0.0.0.0:3030）。
  • RQBIT_UPNP_SERVER_ENABLE: UPnPサーバーの有効化または無効化（例: trueまたはfalse）。
  • RQBIT_UPNP_SERVER_FRIENDLY_NAME: UPnPサーバーのフレンドリーネーム（例: rqbit-media）。
  • RQBIT_EXPERIMENTAL_UTP_LISTEN_ENABLE: uTPリスナーの有効化または無効化（デフォルト: false）。
  • 他の変数や詳細情報については、rqbitを確認してください。

インストール

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

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

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

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

pip install rqbit-mcp

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

RQBIT_URL=http://localhost:3030

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

python -m rqbit_client

ローカル開発用

この方法は、ソースコードを変更したいコントリビューター向けです。 uvを使用します。

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

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

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

uv sync --locked

3. サンプルをコピーして設定ファイルを作成し、設定を追加します。

cp .env.example .env

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

uv run -m rqbit_client

Docker用

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

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

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

2. サンプルをコピーして設定ファイルを作成し、設定を追加します。

cp .env.example .env

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

docker compose up --build -d

4. コンテナのログを表示します。

docker logs rqbit-mcp -f

💻 使用例

Python APIラッパーとして

import asyncio
from rqbit_client.wrapper import RqbitClient

async def main():
    # Read the RQBIT_URL from the .env file or fallback to default (http://localhost:3030)
    async with RqbitClient() as client:
        # Download a torrent
        magnet_link = "magnet:?xt=urn:btih:..."
        torrent = await client.download_torrent(magnet_link)
        print(torrent)

        # Check status
        status = await client.get_torrent_stats(torrent["id"])
        print(status)

        # List torrents
        torrents = await client.list_torrents()
        print(torrents)

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

MCPサーバーとして

from rqbit_client import RqbitMCP

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

MCPクライアント経由

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

• list_torrents: すべてのトレントをリスト表示します。
• download_torrent: マグネットリンクまたはファイルパスを介してトレントをダウンロードします。
• get_torrent_details: 特定のトレントの詳細を取得します。
• get_torrent_stats: 特定のトレントの統計情報/ステータスを取得します。
• pause_torrent: トレントを一時停止します。
• start_torrent: トレントを開始します。
• forget_torrent: トレントを忘れ、ファイルを保持します。
• delete_torrent: トレントとそのファイルを削除します。

Windsurfを使用した例

設定:

{
  "mcpServers": {
    ...
    # with stdio (only requires uv)
    "rqbit-mcp": {
      "command": "uvx",
      "args": [ "rqbit-mcp" ],
      "env": { 
        "RQBIT_URL": "http://localhost:3030", # (Optional) Default rqbit instance URL
        "RQBIT_HTTP_BASIC_AUTH_USERPASS": "username:password" # (Optional) Only if setup in rqbit instance
      }
    },
    # with sse transport (requires installation)
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # with streamable-http transport (requires installation)
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp" 
    },
    ...
  }
}

📜 変更履歴

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

🤝 コントリビュート

コントリビューションは大歓迎です！問題を報告するか、プルリクエストを送信してください。

📄 ライセンス

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