What is Ygg Torrent Mcp

ygg-torrent-mcp is a Python wrapper and MCP server designed for YggTorrent, allowing users to interact with the YggTorrent website programmatically.

Use cases

Use cases include integrating YggTorrent functionalities into custom applications, automating torrent searches, and managing torrent downloads efficiently through a programmatic interface.

How to use

To use ygg-torrent-mcp, you can set it up in a local Python environment or via Docker. After installing the required dependencies and configuring your Ygg passkey, you can run the MCP server and access its functionalities.

Key features

Key features include an API wrapper for YggAPI, local injection of your Ygg passkey into torrent files/magnet links, a standardized MCP server interface, torrent search capabilities, detailed torrent information retrieval, and access to magnet links and torrent categories.

Where to use

ygg-torrent-mcp can be used in various fields such as software development, automation tools, and applications that require torrent functionalities, particularly for users of YggTorrent.

YggTorrent MCP Server & Wrapper

This repository provides a Python wrapper for the YggTorrent website and an MCP (Model Context Protocol) server to interact with it programmatically. This allows for easy integration of YggTorrent functionalities 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
• 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:

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.