Python API Wrapper & MCP Server for rqbit

Python PyPI Actions status License: MIT Ask DeepWiki

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.

Related MCP server: Python REPL MCP Server

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 Torrent Client MCP