rqbit Torrent Client MCP

Python API Wrapper & MCP Server for rqbit

This repository provides a Python API wrapper and an MCP (Model Context Protocol) server for the rqbit torrent client. It allows for easy integration into other applications or services.

Table of Contents

• Features
• Setup
  • Prerequisites
  • Configuration
  • Installation
    • Install from PyPI (Recommended)
    • For Local Development
    • For Docker
• Environment Variables
• Usage
  • As Python API Wrapper
  • As MCP Server
  • Via MCP Clients
    • Example with Windsurf
• Contributing
• Changelog
• License

Features

• API wrapper for the rqbit torrent client.
• MCP server interface for standardized communication (stdio, sse, streamable-http)
• Tools:
  • list_torrents: List all torrents and their details.
  • download_torrent: Download a torrent from a magnet link or a file.
  • get_torrent_details: Get detailed information about a specific torrent.
  • get_torrent_stats: Get stats/status of a specific torrent.
  • pause_torrent: Pause a torrent.
  • start_torrent: Start a torrent.
  • forget_torrent: Forget a torrent, keeping the files.
  • delete_torrent: Delete a torrent and its files.

Setup

Prerequisites

• An running instance of rqbit. (Included in docker compose)
• Python 3.10+ (required for PyPI install).
• uv (for local development)

Configuration

This application requires the URL of your rqbit instance.

Set Environment Variable: Copy .env.example to .env in your project's root directory and edit it with your settings. The application will automatically load variables from .env:

• MCP Server:
  • RQBIT_URL: The URL of the rqbit instance (Default: http://localhost:3030).
  • RQBIT_HTTP_BASIC_AUTH_USERPASS: If setup in rqbit instance.
• Rqbit Instance:
  • RQBIT_HTTP_BASIC_AUTH_USERPASS: The username and password for basic authentication, in the format username:password.
  • RQBIT_HTTP_API_LISTEN_ADDR: The listen address for the HTTP API (e.g., 0.0.0.0:3030).
  • RQBIT_UPNP_SERVER_ENABLE: Enables or disables the UPnP server (e.g., true or false).
  • RQBIT_UPNP_SERVER_FRIENDLY_NAME: The friendly name for the UPnP server (e.g., rqbit-media).
  • RQBIT_EXPERIMENTAL_UTP_LISTEN_ENABLE: Enables or disables the uTP listener (Default: false).
  • Check rqbit for other variables and more information.

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:

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

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

For Local Development

This method is for contributors who want to modify the source code. Using uv:

1. Clone the repository:

2. Install dependencies using uv:

3. Create your configuration file by copying the example and add your settings:

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

For Docker

This method uses Docker to run the server in a container. compose.yaml includes rqbit torrent client.

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

2. Create your configuration file by copying the example and add your settings:

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

4. Access container logs:

Usage

As Python API Wrapper

As MCP Server

Via MCP Clients

Usable with any MCP-compatible client. Available tools:

• list_torrents: List all torrents.
• download_torrent: Download a torrent via magnet link or file path.
• get_torrent_details: Get details of a specific torrent.
• get_torrent_stats: Get stats/status of a specific torrent.
• pause_torrent: Pause a torrent.
• start_torrent: Start a torrent.
• forget_torrent: Forget a torrent, keeping the files.
• delete_torrent: Delete a torrent and its files.

Example with Windsurf

Configuration:

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.