TorBox MCP Server

<p align="center"> <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python"> <img src="https://img.shields.io/badge/Framework-FastMCP-green" alt="Framework"> <img src="https://img.shields.io/badge/License-MIT-lightgrey" alt="License"> </p>

A robust Model Context Protocol (MCP) server that connects your AI agents to Prowlarr and TorBox, allowing for fully autonomous torrent searching, downloading, and media extraction.

Features

• Search for torrents across indexers configured in Prowlarr.
• Send torrents and magnet links directly to TorBox for secure cloud downloading.
• Automatically handles indexer redirects and localhost proxies (e.g., FlareSolverr).
• Inspects downloaded TorBox file trees to extract specific media files.
• Generates secure streaming/download links for downloaded files.
• Built-in guardrails to reject executable files from media requests for security.

Requirements

• Python 3.10+
• TorBox Account (with API Key)
• Prowlarr Instance (Local or Remote)
• Docker (optional, for running Prowlarr/FlareSolverr via the included compose file)

Setup

1. Clone the repository.
2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

1. Copy .env.example to .env and fill in your details:

   PROWLARR_URL=http://localhost:9696
   PROWLARR_API_KEY=your_prowlarr_api_key_here
   TORBOX_API_KEY=your_torbox_api_key_here

1. Start the MCP server:

   python src/server.py

The SSE endpoint is http://localhost:8000/sse. The server binds to 0.0.0.0:8000 by default so that it remains reachable through Docker port publishing. MCP_HOST and MCP_PORT may be used to override the bind address for non-Docker deployments.

To run the complete stack in Docker:

   docker compose up --build -d

In Docker, Prowlarr is reached by its Compose service name at http://prowlarr:9696; do not use localhost for this connection. The localhost value in the local .env example is only for running the MCP server directly on the host.

Prowlarr indexers protected by Cloudflare can take longer than a typical HTTP request. Searches wait up to 120 seconds by default; set PROWLARR_SEARCH_TIMEOUT to change that limit.

The Docker defaults cap in-flight work to prevent slow external services from piling up inside the MCP process:

   MAX_CONCURRENT_PROWLARR_SEARCHES=5
   MAX_CONCURRENT_TORBOX_OPS=3
   METADATA_MAX_RETRIES=30
   METADATA_RETRY_DELAY=5

Torrent files downloaded from Prowlarr are accepted without a size cap. To reduce peak memory use, the server spools larger .torrent payloads to the container temp directory before uploading them to TorBox.

Usage

The server exposes tools to your AI agent natively over MCP:

• search_indexers
• add_to_cloud
• inspect_file_tree
• get_secure_link

License

MIT License