MCP Integration Tool for Multi - platform Torrent Search via Python API

Torrent Search MCP

A project that provides a Python API and an MCP server for programmatically searching for torrents on ThePirateBay, Nyaa, and YggTorrent, supporting multiple integration methods.

Search tools Entertainment and media #Torrent search #API encapsulation #MCP service #Python tool .Python

rating : 2.5 points

downloads : 1

update time : 2025-07-24

What is the Torrent Search MCP Server?

The Torrent Search MCP Server is a service based on the Model Context Protocol (MCP) that allows users to search for and obtain magnet links or torrent files through a standard interface. It supports platforms such as ThePirateBay, Nyaa, and YggTorrent.

How to use the Torrent Search MCP Server?

The service can be used through the command line, Docker containers, or integrated into other applications. Users only need to provide keywords to search for relevant torrents and obtain detailed information or download links.

Applicable scenarios

It is suitable for users who need to quickly find and obtain torrent files, such as media enthusiasts, researchers, or developers. It is also suitable for integration into other applications to achieve automated content retrieval.

Main Features

Multi-platform supportSupports multiple well-known torrent sites such as ThePirateBay, Nyaa, and YggTorrent.

Secure data transferInject the passkey of YggTorrent locally to ensure that sensitive information is not exposed.

Flexible access methodsSupports accessing the service through multiple methods such as the MCP protocol, FastAPI, or Docker containers.

Detailed search resultsReturns information including file name, size, number of seeds, number of downloads, date, and source.

Advantages and Limitations

Advantages

Supports multiple mainstream torrent sites, improving search coverage.

Provides multiple access methods for easy use in different scenarios.

Protects user privacy and avoids exposing the passkey.

Limitations

Some functions depend on external sites and may be affected by network restrictions.

Requires configuring environment variables (such as the passkey of YggTorrent) to fully utilize the functions.

Some advanced functions may require additional installation of dependencies (such as Chromium).

How to Use

Install the service

Install the service package via pip or deploy it using Docker.

Configure environment variables

Create a .env file and set the necessary parameters, such as the passkey of YggTorrent.

Start the service

After running the service, you can interact with it through the command line, MCP client, or FastAPI interface.

Usage Examples

Search for movie resourcesThe user enters 'Inception' to search, and the system returns all relevant torrents, including file names, sizes, number of seeds, and other information.

Obtain anime resourcesThe user enters 'Attack on Titan' to search, and the system returns all relevant anime torrents and provides magnet links.

Frequently Asked Questions

Do I need to register a YggTorrent account?

How to solve DNS problems?

Can it be used in a non-Python environment?

Is the service open source?

Related Resources

GitHub Repository

The address of the project source code and documentation.

PyPI Package

The release page of the Python package.

MCP Protocol Documentation

The official documentation of the Model Context Protocol.

Windsurf Client

A client tool that supports the MCP protocol.

🚀 Torrent Search MCP Server & API

This repository offers a Python API and an MCP (Model Context Protocol) server that enables you to programmatically search for torrents on ThePirateBay, Nyaa, and YggTorrent. It can be easily integrated into other applications or services.

🚀 Quick Start

How to use it with MCP Clients Run it with Docker to bypass common DNS issues

✨ 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 info for a specific torrent by id
- Get magnet link or torrent file for a specific torrent by id

📦 Setup

📋 Prerequisites

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

⚙️ Configuration (Optional)

This application requires a passkey if you want to interact with YggTorrent.

Find your Passkey: On the YggTorrent website, navigate to Mon compte -> PASSKEY field.
Set Environment Variables: The application reads configuration from environment variables. The recommended way to set them is by creating a .env file in your project's root directory. The application will load it automatically. See .env.example for all available options.

📥 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
playwright install --with-deps chromium # If previous command fails

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: stdio):

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 --locked
uvx playwright install --with-deps chromium # If previous command fails

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

cp .env.example .env

Run the MCP server (default: stdio):

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: 8000):

docker compose up --build -d

Access container logs:

docker logs torrent-search-mcp -f

💻 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 library 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:

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

--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_info: Get info for a specific torrent by id.
get_magnet_link_or_torrent_file: Get the magnet link or torrent file for a specific torrent by id.

Example with Windsurf

Configuration:

{
  "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
    },
    ...
  }
}