Ygg Torrent MCP

🚀 YggTorrent MCP Server & Wrapper

This repository offers a Python wrapper for the YggTorrent website and an MCP (Model Context Protocol) server, enabling programmatic interaction with YggTorrent. It facilitates seamless integration of YggTorrent features into other applications or services.

🚀 Quick Start

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

📚 Table of Contents

• ✨ Features
• 📦 Setup
  • 📋 Prerequisites
  • ⚙️ Configuration
  • 💾 Installation
    • 📥 Install from PyPI (Recommended)
    • 💻 For Local Development
    • 🐳 For Docker
• 💻 Usage
  • 🐍 As Python Wrapper
  • 🖥️ As MCP Server
  • 🌐 As FastAPI Server
  • 📡 Via MCP Clients
    • 🌬️ Example with Windsurf
• 🤝 Contributing
• 📜 Changelog
• 📄 License

✨ Features

• API wrapper for YggAPI, an unofficial API for 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 YggTorrent.
  • Get details for a specific torrent.
  • Retrieve magnet links.
  • Retrieve torrent files.
  • Retrieve torrent categories.

📦 Setup

📋 Prerequisites

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

⚙️ Configuration

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

1. 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.
2. 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.

1. Install the package from PyPI:

pip install ygg-torrent-mcp

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

YGG_PASSKEY=your_passkey_here

3. Run the MCP server (default port: 8000):

python -m ygg_torrent

💻 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/ygg-torrent-mcp.git
cd ygg-torrent-mcp

2. Install dependencies using uv:

uv sync

3. Create your configuration file by copying the example and add your passkey:

cp .env.example .env

4. Run the MCP server (default port: 8000):

uv run -m ygg_torrent

🐳 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/ygg-torrent-mcp.git
cd ygg-torrent-mcp

2. Create your configuration file by copying the example and add your passkey:

cp .env.example .env

3. 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 ygg_torrent import ygg_api

results = ygg_api.search_torrents('...')
for torrent in results:
    print(f"{torrent.filename} | {torrent.size} | {torrent.seeders} SE | {torrent.leechers} LE | {torrent.downloads} DL | {torrent.date}")

🖥️ As MCP Server

from ygg_torrent import ygg_mcp

ygg_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 ygg_torrent --fastapi
# Prod
uvicorn ygg_torrent.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.
• download_torrent_file: Download the .torrent file for a torrent.

🌬️ Example with Windsurf

Configuration:

{
  "mcpServers": {
    ...
    # with stdio (only requires uv installed)
    "mcp-ygg-torrent": {
      "command": "uvx",
      "args": ["ygg-torrent-mcp"],
      "env": { "YGG_PASSKEY": "your_passkey_here" }
    }
    # with sse transport (requires installation)
    "mcp-ygg-torrent": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    }
    # with streamable-http transport (requires installation)
    "mcp-ygg-torrent": {
      "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.