Fr Torrent Search MCP Server
This server provides programmatic access to search and download torrents from French providers (LaCale and YggTorrent). It offers:
Core Tools:
search_torrents- Advanced search with intelligent query optimization for TV shows (episodes, seasons, series) and movies. Results are automatically filtered and ranked by quality (1080p preferred), codec efficiency (x265/HEVC), health (seeders/leechers), and size. Returns top 3 recommendations with detailed metadata and reasoning.get_torrent- Retrieve magnet link or torrent file path by IDget_magnet_link- Extract magnet link for a specific torrentdownload_torrent_file- Download .torrent file to a specified directory
Deployment Options:
MCP server with multiple transports (stdio, SSE, streamable-http)
FastAPI HTTP server with REST endpoints
Docker container (bypasses DNS issues)
Python wrapper library for direct integration
Configuration: Requires environment variables for provider authentication (YggTorrent username/password, LaCale passkey). Compatible with MCP clients like Windsurf.
⚠️ DEPRECATED: This project is no longer actively maintained. The underlying FR Torrent websites have become unreliable and may stop working at any time. Use at your own risk.
FR Torrent MCP Server & Wrapper
This repository provides a Python wrapper for the FR Torrent websites and an MCP (Model Context Protocol) server to interact with them programmatically. This allows for easy integration of FR Torrent functionalities into other applications or services.
Quickstart
Related MCP server: Torrent Search MCP Server
Table of Contents
Features
API aggregator for multiple French torrent providers:
YggTorrent (now ygg.gratis): Support via local bridge UwUDev/francisca
La Cale (la-cale.space): Dead — source is no longer available.TODO: Add support for torr9.net and others
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 across all providers
Get torrent
Get magnet link
Download torrent file
Setup
Prerequisites
Python 3.10+ (required for PyPI install).
uv(for local development)Docker and Docker Compose (for Docker setup)
Configuration (Optional)
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.
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 fr-torrent-search-mcpCreate a
.envfile in the directory where you'll run the application and add your configuration:
#FOLDER_TORRENT_FILES=/path/to/target/folderRun the MCP server (default: stdio):
python -m fr_torrent_searchFor 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/fr-torrent-search-mcp.git
cd fr-torrent-search-mcpInstall dependencies using
uv:
uv sync --frozenCreate your configuration file by copying the example:
cp .env.example .envRun the MCP server (default: stdio):
uv run -m fr_torrent_searchFor 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/fr-torrent-search-mcp.git
cd fr-torrent-search-mcpCreate your configuration file by copying the example:
cp .env.example .envBuild and run the container using Docker Compose (default port: 8000):
docker compose up --build -dAccess container logs:
docker logs fr-torrent-search-mcp -fUsage
As Python Wrapper
from fr_torrent_search import fr_torrent_api
results = fr_torrent_api.search_torrents('...', max_items=10)
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 fr_torrent_search import fr_torrent_mcp
fr_torrent_mcp.run(transport="sse")As FastAPI Server
This project also includes a FastAPI server as an alternative way to interact with the FR Torrent 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 fr_torrent_search --mode fastapi
# With uv
uv run -m fr_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:
GET /: Health check endpoint. Returns{"status": "ok"}.POST /torrent/search: Search for torrents (params:query,max_items).GET /torrent/{torrent_id}: Get torrent (returns magnet link or .torrent file).GET /torrent/{torrent_id}/magnet: Get magnet link for a torrent.GET /torrent/{torrent_id}/file: Download .torrent file.GET /docs: Interactive API documentation (Swagger UI).GET /redoc: Alternative API documentation (ReDoc).
Environment variables are configured the same way as for the MCP server.
Via MCP Clients
Usable with any MCP-compatible client. Available tools:
search_torrents: Search for torrents.get_torrent: Get torrent data (magnet or file).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 sse transport (requires installation)
"fr-torrent-search-mcp": {
"serverUrl": "http://127.0.0.1:8000/sse"
}
# with streamable-http transport (requires installation)
"fr-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.
Available Tools
4 toolsdownload_torrent_fileC
Download the torrent file for a specific torrent by id.
Inputs: torrent_id (required), output_dir. Returns: Generic wrapper for non-object return types.
get_magnet_linkB
Get the magnet link for a specific torrent by id.
Inputs: torrent_id (required). Returns: Generic wrapper for non-object return types.
get_torrentC
Get a specific torrent (either magnet link or torrent file path) by id.
Inputs: torrent_id (required). Returns: Generic wrapper for non-object return types.
search_torrentsA
Perform an advanced torrent search across multiple providers.
Arguments:
user_intent: Must reflect user's overall intention (e.g. "latest episode of Breaking Bad").query: Optimized keywords for search. MUST be lowercase and space-separated.
Query Construction Rules:
NO generic terms: remove "movie", "series", "torrent", "download".
NO filler words: remove "the", "a", "an", "and", "of", "with".
NO technical tags: do NOT add "1080p", "h265", "bluray", or episode titles, except if explicitly requested by the user.
TV Shows:
Specific episode:
[show name] sXXeYY(e.g., "shogun s01e05")Full season:
[show name] sXX(e.g., "shogun s01")Full series:
[show name](e.g., "shogun")
Language: Add
multiONLY if the user specifically requests a non-French or multi-language version.
Result Analysis & Ranking:
Quality: Prefer 1080p or 4k, over 720p.
Efficiency: Prefer h265/HEVC for better quality/size ratio.
Health: Maximize seeders + leechers.
Size: Prefer smaller files within the same quality bracket.
Response Requirements:
Recommend the top 3 results maximum.
For each recommendation, include: Filename, Size, Seeds/Leechs, Date, Source, and a 1-sentence "Why this?" reason.
If results are poor or irrelevant, suggest specific keywords to improve the search.
Inputs: user_intent (required), query (required), max_items. Returns: Generic wrapper for non-object return types.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
There is significant overlap between `get_torrent`, `download_torrent_file`, and `get_magnet_link`—all retrieve a torrent by id but differ only in output format. An agent could easily call the wrong tool or be uncertain which one to use.
All four tool names follow a consistent verb_noun pattern in snake_case (download_torrent_file, get_magnet_link, get_torrent, search_torrents), making the naming predictable and uniform.
Four tools is a reasonable count for a focused torrent search server. It covers search and retrieval without being excessive, though the split of retrieval into three tools could be streamlined to two.
The tool surface covers the essential operations: advanced search and retrieval of torrent files/magnet links. A minor gap might be a tool to list available categories or providers, but the core search-to-download workflow is complete.
Maintenance
Related MCP Connectors
A simple MCP server built with FastMCP and python
MCP server for the Vulners.com API
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceA Python MCP server that allows programmatic interaction with YggTorrent, enabling torrent search, details retrieval, and magnet link generation without exposing your Ygg passkey.425 PyPI18MIT
- AlicenseAqualityBmaintenanceA Python MCP server that allows programmatic interaction to find torrents programmatically on ThePirateBay, Nyaa and YggTorrent.7281 PyPI45PythonMIT
- AlicenseBqualityDmaintenancePython wrapper & MCP server for the rqbit API83MIT
- AlicenseAqualityDmaintenanceMCP server for searching, viewing details, and downloading torrents from kinozal.tv38 npm2MIT