Skip to main content
Glama

Torrent Search MCP Server

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

Table of Contents

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.

  1. Find your Passkey: On the YggTorrent website, navigate to Mon compte -> PASSKEY field.
  2. 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.

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

  1. Install the package from PyPI:
pip install torrent-search-mcp crawl4ai-setup # For crawl4ai/playwright playwright install --with-deps chromium # If previous command fails
  1. Create a .env file in the directory where you'll run the application and add your passkey (optional):
YGG_PASSKEY=your_passkey_here
  1. 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:

  1. Clone the repository:
git clone https://github.com/philogicae/torrent-search-mcp.git cd torrent-search-mcp
  1. Install dependencies using uv:
uv sync --locked uvx playwright install --with-deps chromium # If previous command fails
  1. Create your configuration file by copying the example and add your passkey (optional):
cp .env.example .env
  1. 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).

  1. Clone the repository (if you haven't already):
git clone https://github.com/philogicae/torrent-search-mcp.git cd torrent-search-mcp
  1. Create your configuration file by copying the example and add your passkey (optional):
cp .env.example .env
  1. Build and run the container using Docker Compose (default port: 8000):
docker compose up --build -d
  1. 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 }, ... } }

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

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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

  1. Quickstart
    1. Table of Contents
      1. Features
        1. Setup
          1. Prerequisites
          2. Configuration (Optional)
          3. Installation
        2. Usage
          1. As Python Wrapper
          2. As MCP Server
          3. As FastAPI Server
          4. Via MCP Clients
        3. Changelog
          1. Contributing
            1. License

              Related MCP Servers

              • -
                security
                A
                license
                -
                quality
                A Python-based MCP server that crawls websites to extract and save content as markdown files, with features for mapping website structure and links.
                Last updated -
                1
                Python
                MIT License
              • -
                security
                F
                license
                -
                quality
                A Python-based server that helps users easily install and configure other MCP servers across different platforms.
                Last updated -
                2
                Python
                • Apple
                • Linux
              • -
                security
                F
                license
                -
                quality
                A Python-based MCP server that integrates with Plex Media Server API to search for movies and manage playlists in your Plex media library.
                Last updated -
                Python
              • A
                security
                A
                license
                A
                quality
                A Python MCP server that allows programmatic interaction with YggTorrent, enabling torrent search, details retrieval, and magnet link generation without exposing your Ygg passkey.
                Last updated -
                4
                11
                Python
                MIT License
                • Apple
                • Linux

              View all related MCP servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/philogicae/torrent-search-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server