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
• 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.
  • add_torrent: Add a torrent from a magnet link or a file.
  • get_torrent_details: Get detailed information about a specific torrent.
  • pause_torrent: Pause a torrent.
  • start_torrent: Start a torrent.
  • forget_torrent: Remove a torrent from the list.

Setup

Prerequisites

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

Configuration

This application requires the URL of your rqbit instance.

Set Environment Variable: The application reads the URL from the RQBIT_URL environment variable. The recommended way to set this is by creating a .env file in your project's root directory. The application will load it automatically.

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 (with 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 rqbit URL:

4. Run the MCP server (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 rqbit URL:

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

Usage

As Python API Wrapper

As MCP Server

Via MCP Clients

Usable with any MCP-compatible client. Available tools:

• list_torrents: List all torrents.
• add_torrent: Add a torrent via magnet link or file path.
• get_torrent_details: Get details of a specific torrent.
• pause_torrent: Pause a torrent.
• start_torrent: Start a torrent.
• forget_torrent: Forget a torrent.

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.