What can you do with this 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 ID * **`get_magnet_link`** - Extract magnet link for a specific torrent * **`download_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.

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

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

Related MCP server: Torrent Search MCP Server

Features

API aggregator for multiple French torrent providers:
- LaCale: Native support.
- YggTorrent: Support via local bridge (e.g., YggAPI).
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

Active account (for YggTorrent).
Passkey (for LaCale).
Python 3.10+ (required for PyPI install).
uv (for local development)
Docker and Docker Compose (for Docker setup)

Configuration

The application requires configuration for the supported providers.

Set Environment Variables: The application reads configuration from environment variables. The recommended way is by creating a .env file in your project's root directory.

# YGGTorrent Configuration #YGG_ENABLE=0 #YGG_DOMAIN=www.yggtorrent.org #YGG_BASE_URL=http://localhost:8715 YGG_USERNAME= YGG_PASSWORD= #TURBO_ENABLED=true # LaCale Configuration #LA_CALE_ENABLE=0 #LA_CALE_DOMAIN=la-cale.space #LA_CALE_TRACKER=https://tracker.la-cale.space/announce # Find your passkey on https://la-cale.space/profile LA_CALE_PASSKEY= # Target folder for torrent files (Default: ./torrents). #FOLDER_TORRENT_FILES=/path/to/target/folder

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-mcp

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

YGG_USERNAME=your_ygg_username YGG_PASSWORD=your_ygg_password #TURBO_ENABLED=true LA_CALE_PASSKEY=your_la_cale_passkey #FOLDER_TORRENT_FILES=/path/to/target/folder

Run the MCP server (default: stdio):

python -m fr_torrent_search

For 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-mcp

Install dependencies using uv:

uv sync --locked

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

cp .env.example .env

Run the MCP server (default: stdio):

uv run -m fr_torrent_search

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):

git clone https://github.com/philogicae/fr-torrent-search-mcp.git cd fr-torrent-search-mcp

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

cp .env.example .env

Build and run the container using Docker Compose (default port: 8000):

docker compose up --build -d

Access container logs:

docker logs fr-torrent-search-mcp -f

Usage

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.

Fr Torrent Search MCP Server