Skip to main content
Glama
philogicae

Fr Torrent Search MCP Server

by philogicae
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

⚠️ 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

uv Python PyPI Actions status License: MIT Ask DeepWiki

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

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.

  1. Install the package from PyPI:

pip install fr-torrent-search-mcp

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

#FOLDER_TORRENT_FILES=/path/to/target/folder

  1. 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:

  1. Clone the repository:

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

  1. Install dependencies using uv:

uv sync --frozen

  1. Create your configuration file by copying the example:

cp .env.example .env

  1. 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).

  1. Clone the repository (if you haven't already):

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

  1. Create your configuration file by copying the example:

cp .env.example .env

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

docker compose up --build -d

  1. 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.

Available Tools

4 tools
download_torrent_fileC

Download the torrent file for a specific torrent by id.

ParametersJSON Schema
NameRequiredDescriptionDefault
torrent_idYes
output_dirNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It only states 'Download the torrent file' without clarifying if the file is returned directly, saved to disk, or requires authentication. The output_dir parameter suggests saving to a directory, but the description omits this behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no waste, making it highly concise. However, it could be improved by briefly mentioning the optional output_dir parameter to aid agent understanding without adding much length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters and an output schema (not shown), the description should provide enough context for correct invocation. It omits any mention of output_dir, does not explain the output schema, and lacks behavioral detail, resulting in significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The description adds no meaning beyond the schema: it mentions 'by id' matching torrent_id, but does not explain output_dir or its default behavior. This fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Download the torrent file') and the resource ('for a specific torrent by id'), which distinguishes it from siblings like get_magnet_link and get_torrent. However, it lacks explicit differentiation or scope details, so it is slightly below a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (e.g., get_magnet_link, get_torrent). It does not mention prerequisites, context, or alternatives, leaving the agent to infer usage from the action alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_torrentC

Get a specific torrent (either magnet link or torrent file path) by id.

ParametersJSON Schema
NameRequiredDescriptionDefault
torrent_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided so description carries full burden, but it does not disclose behavior such as error handling, read-only nature, or authentication needs. Only states it returns either magnet link or file path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, efficient and front-loaded with the action and resource. However, lacks detail required for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Minimal information given the output schema exists but not described, and no annotation coverage. Agent would need to infer return type from output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and description only adds 'by id', which provides no detail on format or constraints of torrent_id parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses specific verb 'get' and resource 'specific torrent', distinguishes from siblings like download_torrent_file and get_magnet_link by indicating this tool returns either a magnet link or file path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or avoid this tool vs alternatives. Sibling tools are listed but not referenced in the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 multi ONLY if the user specifically requests a non-French or multi-language version.

Result Analysis & Ranking:

  1. Quality: Prefer 1080p or 4k, over 720p.

  2. Efficiency: Prefer h265/HEVC for better quality/size ratio.

  3. Health: Maximize seeders + leechers.

  4. 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
user_intentYes
queryYes
max_itemsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility. It discloses key behaviors: searching multiple providers, query construction rules, ranking criteria (quality, efficiency, health, size), and response format (top 3 with reasons). It also specifies handling of poor results. However, it omits details like provider names, auth needs, or potential rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured into sections (arguments, query rules, ranking, response). Every sentence adds value, though some repetition exists (e.g., 'top 3 results maximum' could be merged). It is appropriately front-loaded with purpose and argument details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown), the description need not detail return values, but it does specify response format (top 3 with filename, size, seeds, etc.). It covers arguments, processing logic, and expectations. Missing are error handling and edge cases (e.g., empty results beyond 'poor results' keyword suggestion). Still, it is largely complete for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, so the description must compensate fully. It provides extensive, prescriptive guidance for user_intent and query, including case, formatting, and content rules. For max_items, it contradicts the default of 10 by stating 'top 3 maximum', adding semantic constraint. This adds far more meaning than the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly states the tool performs an advanced torrent search across multiple providers, which is a specific verb-resource pair. The sibling tools (download_torrent_file, get_magnet_link, get_torrent) indicate this is the search entry point, making it distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive guidance on how to use the arguments and interpret results (query construction, ranking criteria), but does not explicitly state when to use this tool over siblings or provide when-not-to-use scenarios. Usage is implied but lacks direct alternatives comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.2.0
    • Changeddownload_torrent_file7 fields changed
      • addedInput schema / properties / output_dir / anyOf
        Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • addedInput schema / properties / output_dir / default
        Added value: +null
      • removedInput schema / properties / output_dir / type
        Removed value: -"string"
      • changedInput schema / required
        Previous value: -[
-  "torrent_id",
-  "output_dir"
-]New value: +[
+  "torrent_id"
+]
      • addedOutput schema / description
        Added value: +"Generic wrapper for non-object return types."
      • removedOutput schema / properties / result / anyOf
        Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
      • addedOutput schema / properties / result / type
        Added value: +"string"
    • Changedget_magnet_link3 fields changed
      • addedOutput schema / description
        Added value: +"Generic wrapper for non-object return types."
      • removedOutput schema / properties / result / anyOf
        Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
      • addedOutput schema / properties / result / type
        Added value: +"string"
    • Changedget_torrent3 fields changed
      • addedOutput schema / description
        Added value: +"Generic wrapper for non-object return types."
      • removedOutput schema / properties / result / anyOf
        Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
      • addedOutput schema / properties / result / type
        Added value: +"string"
    • Changedsearch_torrents1 field changed
      • addedOutput schema / description
        Added value: +"Generic wrapper for non-object return types."
  2. 4 tool updatesv1.0.4
    • First observeddownload_torrent_file
    • First observedget_magnet_link
    • First observedget_torrent
    • First observedsearch_torrents
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Scored across 4 tools

Disambiguation2/5

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.

Naming Consistency5/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers