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.

Features
Setup
Environment Variables
Usage
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.

Install the package from PyPI:

pip install rqbit-mcp

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

RQBIT_URL=http://localhost:3030

Run the MCP server (default: stdio):

python -m rqbit_client

For Local Development

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

Clone the repository:

git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp

Install dependencies using uv:

uv sync --locked

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

cp .env.example .env

Run the MCP server (default: stdio):

uv run -m rqbit_client

For Docker

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

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

git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp

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

cp .env.example .env

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

docker compose up --build -d

Access container logs:

docker logs rqbit-mcp -f

Usage

As Python API Wrapper

import asyncio
from rqbit_client.wrapper import RqbitClient

async def main():
    # Read the RQBIT_URL from the .env file or fallback to default (http://localhost:3030)
    async with RqbitClient() as client:
        # Download a torrent
        magnet_link = "magnet:?xt=urn:btih:..."
        torrent = await client.download_torrent(magnet_link)
        print(torrent)

        # Check status
        status = await client.get_torrent_stats(torrent["id"])
        print(status)

        # List torrents
        torrents = await client.list_torrents()
        print(torrents)

if __name__ == "__main__":
    asyncio.run(main())

As MCP Server

from rqbit_client import RqbitMCP

RqbitMCP.run(transport="sse") # 'stdio', 'sse', or 'streamable-http'

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:

{
  "mcpServers": {
    ...
    # with stdio (only requires uv)
    "rqbit-mcp": {
      "command": "uvx",
      "args": [ "rqbit-mcp" ],
      "env": { 
        "RQBIT_URL": "http://localhost:3030", # (Optional) Default rqbit instance URL
        "RQBIT_HTTP_BASIC_AUTH_USERPASS": "username:password" # (Optional) Only if setup in rqbit instance
      }
    },
    # with docker (only requires docker)
    "rqbit-mcp": {
      "command": "docker",
      "args": [ "run", "-i", "-p", "8000:8000", "-e", "RQBIT_URL=http://localhost:3030", "-e", "RQBIT_HTTP_BASIC_AUTH_USERPASS=username:password", "philogicae/rqbit-mcp:latest", "rqbit-mcp" ]
    },
    # with sse transport (requires installation)
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # with streamable-http transport (requires installation)
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp" 
    },
    ...
  }
}

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.

Rqbit