# Fr Torrent Search Mcp

> Python API & MCP server to find french torrents programmatically

- **Type:** MCP server
- **Install:** `agentstack add mcp-philogicae-fr-torrent-search-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [philogicae](https://agentstack.voostack.com/s/philogicae)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [philogicae](https://github.com/philogicae)
- **Source:** https://github.com/philogicae/fr-torrent-search-mcp
- **Website:** https://deepwiki.com/philogicae/fr-torrent-search-mcp

## Install

```sh
agentstack add mcp-philogicae-fr-torrent-search-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

[](https://docs.astral.sh/uv/getting-started/installation/)
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/fr-torrent-search-mcp)
[](https://github.com/philogicae/fr-torrent-search-mcp/actions)
[](https://opensource.org/licenses/MIT)
[](https://deepwiki.com/philogicae/fr-torrent-search-mcp)

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](#via-mcp-clients)

> [Run it with Docker to bypass common DNS issues](#for-docker)

## Table of Contents

- [Features](#features)
- [Setup](#setup)
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
- [Installation](#installation)
- [Install from PyPI (Recommended)](#install-from-pypi-recommended)
- [For Local Development](#for-local-development)
- [For Docker](#for-docker)
- [Usage](#usage)
- [As Python Wrapper](#as-python-wrapper)
- [As MCP Server](#as-mcp-server)
- [As FastAPI Server](#as-fastapi-server)
- [Via MCP Clients](#via-mcp-clients)
- [Example with Windsurf](#example-with-windsurf)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#license)

## Features

- API aggregator for multiple French torrent providers:
  - **YggTorrent (now ygg.gratis)**: Support via local bridge [UwUDev/francisca](https://github.com/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`](https://github.com/astral-sh/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:

```bash
pip install fr-torrent-search-mcp
```

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

```env
#FOLDER_TORRENT_FILES=/path/to/target/folder
```

3.  Run the MCP server (default: stdio):

```bash
python -m fr_torrent_search
```

#### For Local Development

This method is for contributors who want to modify the source code.
Using [`uv`](https://github.com/astral-sh/uv):

1.  Clone the repository:

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

2.  Install dependencies using `uv`:

```bash
uv sync --frozen
```

3.  Create your configuration file by copying the example:

```bash
cp .env.example .env
```

4.  Run the MCP server (default: stdio):

```bash
uv run -m fr_torrent_search
```

#### For Docker

This method uses Docker to run the server in a container.

[compose.yaml](./compose.yaml) is configured to bypass DNS issues (using [quad9](https://quad9.net/) DNS).

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

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

2.  Create your configuration file by copying the example:

```bash
cp .env.example .env
```

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

```bash
docker compose up --build -d
```

4.  Access container logs:

```bash
docker logs fr-torrent-search-mcp -f
```

## Usage

### As Python Wrapper

```python
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

```python
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:**

```bash
# With Python
python -m fr_torrent_search --mode fastapi
# With uv
uv run -m fr_torrent_search --mode fastapi
```

- `--host `: Default: `0.0.0.0`.
- `--port `: Default: `8000`.
- `--reload`: Enables auto-reloading when code changes (useful for development).
- `--workers `: Default: `1`.

The FastAPI server will then be accessible at `http://:`

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

```json
{
  "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](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](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [philogicae](https://github.com/philogicae)
- **Source:** [philogicae/fr-torrent-search-mcp](https://github.com/philogicae/fr-torrent-search-mcp)
- **License:** MIT
- **Homepage:** https://deepwiki.com/philogicae/fr-torrent-search-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-philogicae-fr-torrent-search-mcp
- Seller: https://agentstack.voostack.com/s/philogicae
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.