金大哥 - torrent-search-mcp MCP 详情

article

README

🚀 种子搜索MCP服务器与API

本项目提供了一个Python API和一个MCP（模型上下文协议）服务器，用于在ThePirateBay、Nyaa和YggTorrent上以编程方式搜索种子。它便于集成到其他应用程序或服务中。

🚀 快速开始

如何与MCP客户端一起使用使用Docker运行以绕过常见的DNS问题

📑 目录

主要特性
安装设置
使用方法
贡献代码
更新日志
许可证

✨ 主要特性

为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进行交互，此应用程序需要一个通行证密钥。

查找您的通行证密钥：在YggTorrent网站上，导航到Mon compte -> PASSKEY字段。
设置环境变量：应用程序从环境变量中读取配置。推荐的设置方法是在项目的根目录下创建一个.env文件。应用程序将自动加载它。有关所有可用选项，请参阅.env.example。

安装方式

选择以下其中一种安装方法。

从PyPI安装（推荐）

此方法最适合将该包作为库使用或在不修改代码的情况下运行服务器。

从PyPI安装该包：

pip install torrent-search-mcp
crawl4ai-setup # 用于crawl4ai/playwright
playwright install --with-deps chromium # 如果上一个命令失败

在运行应用程序的目录中创建一个.env文件，并添加您的通行证密钥（可选）：

YGG_PASSKEY=your_passkey_here

运行MCP服务器（默认：标准输入输出）：

python -m torrent_search

本地开发安装

此方法适用于想要修改源代码的贡献者。使用 uv：

克隆仓库：

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

使用uv安装依赖项：

uv sync --locked
uvx playwright install --with-deps chromium # 如果上一个命令失败

通过复制示例文件创建您的配置文件，并添加您的通行证密钥（可选）：

cp .env.example .env

运行MCP服务器（默认：标准输入输出）：

uv run -m torrent_search

使用Docker安装

此方法使用Docker在容器中运行服务器。

compose.yaml配置为绕过DNS问题（使用 quad9 DNS）。

克隆仓库（如果您还没有这样做）：

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

通过复制示例文件创建您的配置文件，并添加您的通行证密钥（可选）：

cp .env.example .env

使用Docker Compose构建并运行容器（默认端口：8000）：

docker compose up --build -d

访问容器日志：

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 文件。

torrent-search-mcp