MCP 服务器

Torrent Search MCP Server

A Python MCP server that allows programmatic interaction to find torrents programmatically on ThePirateBay, Nyaa and YggTorrent.

Tools

search_torrents

Search for torrents on sources [thepiratebay.org, nyaa.si, yggtorrent].

get_ygg_torrent_details

Get details about a specific torrent coming from YGG Torrent source only.

get_ygg_magnet_link

Get the magnet link for a specific torrent coming from YGG Torrent source only.

README

Torrent Search MCP Server & API

This repository provides a Python API and an MCP (Model Context Protocol) server to find torrents programmatically on ThePirateBay, Nyaa and YggTorrent. It allows for easy integration into other applications or services.

Quickstart

How to use it with MCP Clients

Run it with Docker to bypass common DNS issues

Features
Setup
Usage
Contributing
Changelog
License

Features

API wrapper for ThePirateBay, Nyaa and YggTorrent.
- Your Ygg passkey is injected locally into the torrent file/magnet link, ensuring it's not exposed externally
MCP server interface for standardized communication (stdio, sse, streamable-http)
FastAPI server interface for alternative HTTP access (e.g., for direct API calls or testing)
Tools:
- Search for torrents on ThePirateBay, Nyaa and YggTorrent
- Get details for a specific YGG torrent
- Retrieve YGG magnet links

Setup

Prerequisites

An active YggTorrent account and passkey (Optional).
Python 3.10+ (required for PyPI install).
uv (for local development)
Docker and Docker Compose (for Docker setup)

Configuration (Optional)

This application requires your YggTorrent passkey to interact with the API.

Find your Passkey: On the YggTorrent website, navigate to Mon compte -> Mes paramètres. Your passkey is part of the tracker URL, which looks like http://tracker.p2p-world.net:8080/{YOUR_PASSKEY}/announce.
Set Environment Variable: The application reads the passkey from the YGG_PASSKEY environment variable. The recommended way to set this is by creating a .env file in your project's root directory. The application will load it automatically.

Installation

Choose one of the following installation methods.

Install from PyPI (Recommended)

This method is best for using the package as a library or running the server without modifying the code.

Install the package from PyPI:

pip install torrent-search-mcp
crawl4ai-setup # For crawl4ai/playwright
# If it fails, try:
uvx playwright install --with-deps chromium

Create a .env file in the directory where you'll run the application and add your passkey (optional):

YGG_PASSKEY=your_passkey_here

Run the MCP server (default port: 8000):

python -m torrent_search

For Local Development

This method is for contributors who want to modify the source code. Using uv:

Clone the repository:

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

Install dependencies using uv:

uv sync
crawl4ai-setup # For crawl4ai/playwright
# If it fails, try:
uvx playwright install --with-deps chromium

Create your configuration file by copying the example and add your passkey (optional):

cp .env.example .env

Run the MCP server (default port: 8000):

uv run -m torrent_search

For Docker

This method uses Docker to run the server in a container.

compose.yaml is configured to bypass DNS issues (using quad9 DNS).

Clone the repository (if you haven't already):

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

Create your configuration file by copying the example and add your passkey (optional):

cp .env.example .env

Build and run the container using Docker Compose (default port: 8765):

docker-compose -f docker/compose.yaml up --build [-d]

Usage

As Python Wrapper

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}")

As MCP Server

from torrent_search import torrent_search_mcp

torrent_search_mcp.run(transport="sse")

As FastAPI Server

This project also includes a FastAPI server as an alternative way to interact with the YggTorrent functionalities via a standard HTTP API. This can be useful for direct API calls, integration with other web services, or for testing purposes.

Running the FastAPI Server:

# Dev
python -m torrent_search --fastapi
# Prod
uvicorn torrent_search.fastapi_server:app

--host <host>: Default: 0.0.0.0.
--port <port>: Default: 8000.
--reload: Enables auto-reloading when code changes (useful for development).
--workers <workers>: Default: 1.

The FastAPI server will then be accessible at http://<host>:<port>

Available Endpoints: The FastAPI server exposes similar functionalities to the MCP server. Key endpoints include:

/: A simple health check endpoint. Returns {"status": "ok"}.
/docs: Interactive API documentation (Swagger UI).
/redoc: Alternative API documentation (ReDoc).

Environment variables (like YGG_PASSKEY) are configured the same way as for the MCP server (via an .env file in the project root).

Via MCP Clients

Usable with any MCP-compatible client. Available tools:

search_torrents: Search for torrents.
get_torrent_details: Get details of a specific torrent.
get_magnet_link: Get the magnet link for a torrent.

Example with Windsurf

Configuration:

{
  "mcpServers": {
    ...
    # with stdio + sudo (only requires uv and playwright installed)
    # Install playwright first:
    # uvx playwright install --with-deps chromium
    "mcp-torrent-search": {
      "command": "uvx",
      "args": ["torrent-search-mcp"],
      "env": { "YGG_PASSKEY": "your_passkey_here" } # optional
    },
    # with stdio + no-sudo (only requires uv)
    "mcp-torrent-search": {
      "command": "sh",
      "args": [
        "-c",
        "uvx playwright install --with-deps chromium && uvx torrent_search"
      ],
      "env": { "YGG_PASSKEY": "your_passkey_here" } # optional
    },
    # with sse transport (requires installation)
    "mcp-torrent-search": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    }
    # with streamable-http transport (requires installation)
    "mcp-torrent-search": {
      "serverUrl": "http://127.0.0.1:8000/mcp" # not yet supported by every client
    }
    ...
  }
}