Torrent Search MCP

🚀 Torrent Search MCP Server & API

このリポジトリは、Python APIとMCP（Model Context Protocol）サーバーを提供し、ThePirateBay、Nyaa、YggTorrentでトレントをプログラムで検索できます。他のアプリケーションやサービスへの簡単な統合を可能にします。

🚀 クイックスタート

MCPクライアントでの使用方法 一般的なDNS問題を回避するためにDockerで実行する方法

📑 目次

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

✨ 主な機能

• ThePirateBay、Nyaa、YggTorrent用のAPIラッパー。
  • Yggのパスキーはトレントファイル/マグネットリンクにローカルで注入され、外部に露出することはありません
• 標準化された通信（stdio、sse、streamable-http）用のMCPサーバーインターフェイス
• 代替HTTPアクセス用のFastAPIサーバーインターフェイス（例：直接のAPI呼び出しやテスト用）
• ツール:
  • ThePirateBay、Nyaa、YggTorrentでトレントを検索する
  • IDで特定のトレントの情報を取得する
  • IDで特定のトレントのマグネットリンクまたはトレントファイルを取得する

📦 インストール

前提条件

• 有効なYggTorrentアカウントとパスキー（オプション）。
• Python 3.10以上（PyPIインストールに必要）。
• uv（ローカル開発用）
• Chromiumとその必要な依存関係
• DockerとDocker Compose（Dockerセットアップ用）

設定（オプション）

このアプリケーションは、YggTorrentとやり取りする場合はパスキーが必要です。

1. パスキーを見つける: YggTorrentウェブサイトで、Mon compte -> PASSKEYフィールドに移動します。
2. 環境変数を設定する: アプリケーションは環境変数から設定を読み取ります。推奨される設定方法は、プロジェクトのルートディレクトリに.envファイルを作成することです。アプリケーションは自動的に読み込みます。利用可能なオプションは.env.exampleを参照してください。

インストール方法

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

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

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

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

pip install torrent-search-mcp
crawl4ai-setup # For crawl4ai/playwright
playwright install --with-deps chromium # If previous command fails

2. アプリケーションを実行するディレクトリに.envファイルを作成し、パスキーを追加します（オプション）。

YGG_PASSKEY=your_passkey_here

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

python -m torrent_search

ローカル開発用

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

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

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

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

uv sync --locked
uvx playwright install --with-deps chromium # If previous command fails

3. サンプルファイルをコピーして設定ファイルを作成し、パスキーを追加します（オプション）。

cp .env.example .env

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

uv run -m torrent_search

Docker用

この方法は、Dockerを使用してサーバーをコンテナ内で実行します。

compose.yamlは、DNS問題を回避するように構成されています（quad9 DNSを使用）。

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

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

2. サンプルファイルをコピーして設定ファイルを作成し、パスキーを追加します（オプション）。

cp .env.example .env

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

docker compose up --build -d

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

docker logs torrent-search-mcp -f

💻 使用例

Pythonラッパーとして

from torrent_search import torrent_search_api

results = torrent_search_api.search_torrents('...')
for torrent in results:
    print(f"{torrent.filename} | {torrent.size} | {torrent.seeders} SE | {torrent.leechers} LE | {torrent.date} | {torrent.source}")

MCPサーバーとして

from torrent_search import torrent_search_mcp

torrent_search_mcp.run(transport="sse")

FastAPIサーバーとして

このプロジェクトには、標準的なHTTP APIを介してライブラリとやり取りするためのFastAPIサーバーも含まれています。これは、直接のAPI呼び出し、他のWebサービスとの統合、またはテスト目的に役立ちます。

FastAPIサーバーの実行方法:

# With Python
python -m torrent_search --mode fastapi
# With uv
uv run -m torrent_search --mode fastapi

• --host <host>: デフォルト: 0.0.0.0。
• --port <port>: デフォルト: 8000。
• --reload: コードが変更されたときに自動リロードを有効にします（開発時に便利）。
• --workers <workers>: デフォルト: 1。

FastAPIサーバーはhttp://<host>:<port>でアクセスできます。

利用可能なエンドポイント: FastAPIサーバーは、MCPサーバーと同様の機能を公開します。主要なエンドポイントには以下が含まれます。

• /: 簡単なヘルスチェックエンドポイント。{"status": "ok"}を返します。
• /docs: 対話型APIドキュメント（Swagger UI）。
• /redoc: 代替APIドキュメント（ReDoc）。

環境変数（YGG_PASSKEYなど）は、MCPサーバーと同じ方法で構成されます（プロジェクトルートの.envファイルを介して）。

MCPクライアント経由

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

• search_torrents: トレントを検索します。
• get_torrent_info: IDで特定のトレントの情報を取得します。
• get_magnet_link_or_torrent_file: IDで特定のトレントのマグネットリンクまたはトレントファイルを取得します。

Windsurfを使用した例

設定:

{
  "mcpServers": {
    ...
    # with stdio (only requires uv)
    "torrent-search-mcp": {
      "command": "uvx",
      "args": [ "torrent-search-mcp" ],
      "env": { "YGG_PASSKEY": "your_passkey_here" } # optional
    },
    # with sse transport (requires installation)
    "torrent-search-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # with streamable-http transport (requires installation)
    "torrent-search-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp" # not yet supported by every client
    },
    ...
  }
}

📝 変更履歴

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

🤝 コントリビュート

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

📄 ライセンス

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