What can you do with this server?

The Torrent Search MCP Server allows you to programmatically search and retrieve torrent data from multiple sources: * Search Torrents: Query ThePirateBay, Nyaa, and YggTorrent with customizable source selection and result limits * Get YggTorrent Details: Retrieve specific information about a YggTorrent torrent using its ID, with an option to include the magnet link * Get YggTorrent Magnet Link: Directly fetch the magnet link for a specific YggTorrent torrent

Which integrations are available for this server?

Provides a containerized deployment option with preconfigured DNS settings (using quad9) to bypass common connection issues when accessing torrent sites Supports configuration through .env files for storing sensitive information like YggTorrent passkeys Includes a FastAPI server as an alternative interface with interactive API documentation (Swagger UI and ReDoc) for direct HTTP access Available as a PyPI package for easy installation and integration into other Python applications Provides a Python API wrapper for programmatic access to torrent search functionality Uses Shields.io for generating status badges in the README Offers Swagger UI documentation for the FastAPI interface, enabling easy API exploration and testing

How do I use Torrent Search MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Torrent Search MCP Server search for the latest Ubuntu ISO torrent" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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, YggTorrent and La Cale. 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

Related MCP server: MCP Builder

Features

API wrapper for ThePirateBay, Nyaa, YggTorrent and La Cale.
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 across all available sources
- Get magnet link or torrent file for a specific torrent by id

Setup

Prerequisites

An active YggTorrent account with username and password (Optional).
An active La Cale account with 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 credentials if you want to interact with YggTorrent or La Cale.

YggTorrent: Username and password from your account.
La Cale: Find your passkey on the La Cale website at https://la-cale.space/profile.
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 credentials (optional):

YGG_USERNAME=your_username_here YGG_PASSWORD=your_password_here LA_CALE_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

Create your configuration file by copying the example and add your credentials (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"}.
/torrent/search: Search for torrents (POST request with query and optional max_items parameters).
/torrent/{torrent_id}: Get magnet link or torrent file for a specific torrent by id.
/docs: Interactive API documentation (Swagger UI).
/redoc: Alternative API documentation (ReDoc).

Environment variables (like YGG_USERNAME, YGG_PASSWORD, LA_CALE_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 across all available sources (ThePirateBay, Nyaa, YggTorrent, La Cale).
get_torrent: Get the magnet link or torrent file for a specific torrent by id.

Available resources:

data://torrent_sources: Get the list of available torrent sources.

Example with Windsurf

Configuration:

{ "mcpServers": { ... # with stdio (only requires uv) "torrent-search-mcp": { "command": "uvx", "args": [ "torrent-search-mcp" ], "env": { "YGG_LOCAL_API": "http://localhost:3456", # YggTorrent instance URL "LA_CALE_PASSKEY": "your_passkey_here" # La Cale passkey } # 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 }, ... } }

Changelog

See CHANGELOG.md for a history of changes to this project.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Reddit Discussion

Related Servers

Torrent Search MCP Server