Torrent Search MCP Server

Torrent搜索MCP服务器和API

     

该存储库提供了一个Python API和一个MCP（模型上下文协议）服务器，用于在 海盗湾, 尼亚, YggTorrent （现在） 我自由了。) 和 路它允许轻松集成到其他应用程序或服务中。

快速启动

如何将其与MCP客户端一起使用

目录

• 特性
• 设置

- 先决条件 - 配置 - 安装 - 从PyPI安装（推荐） - 促进地方发展 -

• 用法

- 作为Python包装器 - 作为MCP服务器 - 作为FastAPI服务器 - 通过MCP客户端 - Windsurf示例

• 贡献
• 更新日志
• 许可证

特性

• 的API包装 海盗湾, 尼亚, YggTorrent （现在） 我自由了。) 和 路.
• 用于标准化通信的MCP服务器接口（stdio、sse、流式http）
• FastAPI服务器接口，用于替代HTTP访问（例如，用于直接API调用或测试）
• 工具：

- 在所有可用来源中搜索种子 - 按id获取特定种子的磁铁链接或种子文件

设置

先决条件

• Python 3.10+（安装PyPI需要）。
• uv （用于地方发展）
• Docker和Docker Compose（用于Docker设置）
• LaCale的密钥（可选）。在上创建您的apikeyhttps://la-cale.space/settings/api-keys

配置（可选）

如果您想与La Cale交互，此应用程序需要凭据。

1. 路：在La Cale网站上找到您的API密钥。
2. 设置环境变量：应用程序从环境变量读取配置。建议的设置方式是创建 .env 项目根目录中的文件。应用程序将自动加载它。看 .env.example 所有可用选项。

安装

选择以下安装方法之一。

从PyPI安装（推荐）

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

1. 从PyPI安装软件包：

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

1. 创建一个 .env 运行应用程序并添加凭据的目录中的文件（可选）：

LA_CALE_API_KEY=your_api_key_here

1. 运行MCP服务器（默认：stdio）：

python -m torrent_search

促进地方发展

此方法适用于希望修改源代码的贡献者。 使用 uv:

1. 克隆存储库：

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

1. 使用安装依赖项 uv:

uv sync --locked
uvx playwright install --with-deps chromium

1. 通过复制示例创建配置文件并添加凭据（可选）：

cp .env.example .env

1. 运行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

1. 通过复制示例创建配置文件并对其进行修改（可选）：

cp .env.example .env

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

docker compose up --build -d

1. 访问容器日志：

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服务器：

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

• --host ：默认值： 0.0.0.0.
• `--port

：默认值： 8000`.

• --reload：启用代码更改时的自动重新加载（对开发很有用）。
• --workers ：默认值： 1.

然后，可以在以下位置访问FastAPI服务器 http://:

可用端点： FastAPI服务器向MCP服务器公开了类似的功能。关键端点包括：

• /：一个简单的健康检查终点。退货 {"status": "ok"}.
• /torrent/search：搜索种子（POST请求 query 可选 max_items 参数）。
• /torrent/{torrent_id}：按id获取特定种子的磁铁链接或种子文件。
• /docs：交互式API文档（Swagger UI）。
• /redoc：API替代文件（ReDoc）。

环境变量的配置方式与MCP服务器相同（通过 .env 项目根目录中的文件）。

通过MCP客户端

适用于任何兼容MCP的客户端。可用工具：

• search_torrents：搜索所有可用来源（ThePirateBay、Nyaa、La Cale）的种子。
• get_torrent：按id获取特定种子的磁铁链接或种子文件。

可用资源：

• data://torrent_sources：获取可用种子源的列表。

Windsurf示例

配置：

{
  "mcpServers": {
    ...
    # with stdio (only requires uv)
    "torrent-search-mcp": {
      "command": "uvx",
      "args": [ "torrent-search-mcp" ]
    },
    # 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
    },
    ...
  }
}

更新日志

看 更改日志.md 查看此项目的更改历史。

贡献

欢迎投稿！请打开问题或提交拉取请求。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。