YggTorrent MCP Server
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
.torrentfile 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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YggTorrent MCP Server search for the latest Marvel movies"
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.
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.
⚠️ DEPRECATED - This repository is no longer maintained
Please use one of the following alternatives instead:
Quickstart
How to use it with MCP Clients > Run it with Docker to bypass common DNS issues
Related MCP server: MCP Builder
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->PASSKEYfield.Set Environment Variable: The application reads the passkey from the
YGG_PASSKEYenvironment variable. The recommended way to set this is by creating a.envfile 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:
pip install ygg-torrent-mcpCreate a
.envfile in the directory where you'll run the application and add your passkey:
YGG_PASSKEY=your_passkey_hereRun the MCP server (default: stdio):
python -m ygg_torrentFor 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/ygg-torrent-mcp.git
cd ygg-torrent-mcpInstall dependencies using
uv:
uv sync --lockedCreate your configuration file by copying the example and add your passkey:
cp .env.example .envRun the MCP server (default: stdio):
uv run -m ygg_torrentFor 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/ygg-torrent-mcp.git
cd ygg-torrent-mcpCreate your configuration file by copying the example and add your passkey:
cp .env.example .envBuild and run the container using Docker Compose (default port: 8000):
docker compose up --build -dAccess container logs:
docker logs ygg-torrent-mcp -fUsage
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:
# With Python
python -m ygg_torrent --mode fastapi
# With uv
uv run -m ygg_torrent --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_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)
"ygg-torrent-mcp": {
"command": "uvx",
"args": ["ygg-torrent-mcp"],
"env": { "YGG_PASSKEY": "your_passkey_here" }
}
# with sse transport (requires installation)
"ygg-torrent-mcp": {
"serverUrl": "http://127.0.0.1:8000/sse"
}
# with streamable-http transport (requires installation)
"ygg-torrent-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.
Available Tools
4 toolsdownload_torrent_fileC
Download the torrent file.
Inputs: output_dir (required), torrent_id (required).
get_magnet_linkC
Get the magnet link for a specific torrent.
Inputs: torrent_id (required).
get_torrent_detailsC
Get details about a specific torrent.
Inputs: torrent_id (required), with_magnet_link.
search_torrentsC
Search for torrent files.
Inputs: query (required), categories, limit, order_by, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: search_torrents finds torrents, get_torrent_details retrieves metadata, get_magnet_link provides a magnet link, and download_torrent_file downloads the file. An agent can easily distinguish between these operations.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., search_torrents, get_torrent_details). The naming is predictable and readable throughout the set.
With 4 tools, the server is well-scoped for torrent operations, covering search, details retrieval, magnet links, and downloads. Each tool earns its place without being overly sparse or bloated.
The toolset provides complete coverage for torrent interaction: search, view details, get magnet links, and download files. There are no obvious gaps in the workflow for this domain.
Related MCP Connectors
A simple MCP server built with FastMCP and python
MCP server for the Vulners.com API
Primarily to be used as a template repository for developing MCP servers with FastMCP in Python, P…
Related MCP Servers
- FlicenseCqualityDmaintenanceThis 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.1-
- AlicenseBqualityFmaintenanceA Python-based server that helps users easily install and configure other MCP servers across different platforms.22MIT
- FlicenseAqualityDmaintenanceA Python-based MCP server that integrates with Plex Media Server API to search for movies and manage playlists in your Plex media library.97-
- AlicenseAqualityBmaintenanceA Python MCP server that allows programmatic interaction to find torrents programmatically on ThePirateBay, Nyaa and YggTorrent.7151 PyPI45PythonMIT