rqbit-mcp

philogicae/rqbit-mcp

3.3

If you are the rightful owner of rqbit-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The rqbit-mcp repository provides a Python API wrapper and an MCP server for the rqbit torrent client, facilitating easy integration into other applications or services.

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

  • 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:
pip install rqbit-mcp
  1. Create a .env file in the directory where you'll run the application and add your rqbit URL:
RQBIT_URL=http://localhost:3030
  1. 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:

  1. Clone the repository:
git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp
  1. Install dependencies using uv:
uv sync --locked
  1. Create your configuration file by copying the example and add your settings:
cp .env.example .env
  1. 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.

  1. Clone the repository (if you haven't already):
git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp
  1. Create your configuration file by copying the example and add your settings:
cp .env.example .env
  1. Build and run the container using Docker Compose (default port: 8000):
docker compose up --build -d
  1. 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 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 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 file for details.