Torrent Search MCP

🚀 種子搜索MCP服務器與API

本項目提供了一個Python API和一個MCP（模型上下文協議）服務器，用於在ThePirateBay、Nyaa和YggTorrent上以編程方式搜索種子。它便於集成到其他應用程序或服務中。

🚀 快速開始

如何與MCP客戶端一起使用 使用Docker運行以繞過常見的DNS問題

📑 目錄

• 主要特性
• 安裝設置
  • 前提條件
  • 配置（可選）
  • 安裝方式
    • 從PyPI安裝（推薦）
    • 本地開發安裝
    • 使用Docker安裝
• 使用方法
  • 作為Python包裝器使用
  • 作為MCP服務器使用
  • 作為FastAPI服務器使用
  • 通過MCP客戶端使用
    • 使用Windsurf的示例
• 貢獻代碼
• 更新日誌
• 許可證

✨ 主要特性

• 為ThePirateBay、Nyaa和YggTorrent提供API包裝器。
  • 您的Ygg通行證密鑰會在本地注入到種子文件/磁力鏈接中，確保不會對外暴露
• 提供MCP服務器接口，用於標準化通信（標準輸入輸出、服務器發送事件、可流式HTTP）
• 提供FastAPI服務器接口，用於替代HTTP訪問（例如，用於直接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。

安裝方式

選擇以下其中一種安裝方法。

從PyPI安裝（推薦）

此方法最適合將該包作為庫使用或在不修改代碼的情況下運行服務器。

1. 從PyPI安裝該包：

pip install torrent-search-mcp
crawl4ai-setup # 用於crawl4ai/playwright
playwright install --with-deps chromium # 如果上一個命令失敗

2. 在運行應用程序的目錄中創建一個.env文件，並添加您的通行證密鑰（可選）：

YGG_PASSKEY=your_passkey_here

3. 運行MCP服務器（默認：標準輸入輸出）：

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 # 如果上一個命令失敗

3. 通過複製示例文件創建您的配置文件，並添加您的通行證密鑰（可選）：

cp .env.example .env

4. 運行MCP服務器（默認：標準輸入輸出）：

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服務器使用

本項目還包含一個FastAPI服務器，作為通過標準HTTP API與庫進行交互的另一種方式。這對於直接API調用、與其他Web服務集成或用於測試目的非常有用。

運行FastAPI服務器：

# 使用Python運行
python -m torrent_search --mode fastapi
# 使用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": {
    ...
    # 使用標準輸入輸出（僅需要uv）
    "torrent-search-mcp": {
      "command": "uvx",
      "args": [ "torrent-search-mcp" ],
      "env": { "YGG_PASSKEY": "your_passkey_here" } # 可選
    },
    # 使用服務器發送事件傳輸（需要安裝）
    "torrent-search-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # 使用可流式HTTP傳輸（並非每個客戶端都支持）
    "torrent-search-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp"
    },
    ...
  }
}

📚 詳細文檔

請參閱 CHANGELOG.md 以瞭解本項目的更改歷史。

🔧 貢獻代碼

歡迎貢獻代碼！請打開一個問題或提交一個拉取請求。

📄 許可證

本項目採用MIT許可證 - 有關詳細信息，請參閱 LICENSE 文件。