This server enables programmatic interaction with YggTorrent through a standardized API interface. You can:
- Search for torrents using keywords, with options for pagination, ordering, and category filters
- Retrieve detailed information about a specific torrent by its ID, optionally including the magnet link
- Obtain the magnet link for a specific torrent by its ID
- Download the
.torrent
file for a specific torrent to a specified output directory
Provides containerized deployment of the YggTorrent MCP server with Docker and Docker Compose for easy setup and isolation.
Supports configuration through environment variables using .env files for storing sensitive information like the YggTorrent passkey.
Enables cloning the YggTorrent MCP repository directly from GitHub for local installation and development.
Allows installation of the YggTorrent MCP package directly via pip from the Python Package Index.
Supports direct integration with Python applications through a wrapper library that can be imported and used programmatically.
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
Table of Contents
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.
- Find your Passkey: On the YggTorrent website, navigate to
Mon compte
->Mes paramètres
. Your passkey is part of the tracker URL, which looks likehttp://tracker.p2p-world.net:8080/{YOUR_PASSKEY}/announce
. - 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.
- Install the package from PyPI:
- Create a
.env
file in the directory where you'll run the application and add your passkey:
- Run the MCP server (default port: 8000):
For Local Development
This method is for contributors who want to modify the source code.
Using uv
:
- Clone the repository:
- Install dependencies using
uv
:
- Create your configuration file by copying the example and add your passkey:
- Run the MCP server (default port: 8000):
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):
- Create your configuration file by copying the example and add your passkey:
- Build and run the container using Docker Compose (default port: 8765):
Usage
As Python Wrapper
As MCP Server
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:
--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.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Python MCP server that allows programmatic interaction with YggTorrent, enabling torrent search, details retrieval, and magnet link generation without exposing your Ygg passkey.
Related MCP Servers
- -securityFlicense-qualityThis is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.Last updated -Python
- -securityFlicense-qualityA Python-based server that helps users easily install and configure other MCP servers across different platforms.Last updated -2Python
- -securityFlicense-qualityA 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
- -securityFlicense-qualityA Python implementation of the MCP server that enables AI models to connect with external tools and data sources through a standardized protocol, supporting tool invocation and resource access via JSON-RPC.Last updated -1Python