Skip to content
BranchesTags

Repository files navigation

🧲 qBittorrent MCP Server (Rust) 🤖

Coveralls task ci

Warning

This project is currently in active development (v0.3.6) and is not production-ready. Features may change, and breaking changes may occur without notice.

A Model Context Protocol (MCP) server for qBittorrent, written in Rust. This tool empowers AI agents to interact with and manage your qBittorrent instance using natural language.

✨ Features

  • 🌐 Search: Search for torrents using qBittorrent's built-in search engine plugins.
  • 🗃️ Torrent Management:
    • Manage multiple qBittorrent instances simultaneously.
    • List all torrents with status, progress, and speed.
    • Add torrents via Magnet URIs or HTTP URLs.
    • Unified Control: Perform actions like pause, resume, reannounce, set category, and add tags via a single manage_torrents tool.
  • 🔍 Torrent Inspection:
    • Consolidated Inspection: Retrieve properties, files, and trackers in a single call via inspect_torrent.
    • Deep file listing and tracker status monitoring.
  • 🚥 Global Control:
    • System Health: Monitor global speeds, data usage, and limits via a unified get_system_info tool.
    • Ban peers and update application preferences.
  • 🏷️ Categories & Tags: Organize torrents using categories and tags with simplified management tools.
  • 📣 Proactive Notifications: Receive real-time notifications when downloads finish (powered by the Sync API).
  • 🧹 Maintenance Macros:
    • cleanup_completed: Auto-remove torrents based on seeding ratio or age.
    • mass_rename: Bulk rename files within torrents using Regex.
    • find_duplicates: Identify redundant downloads by name.
  • 💡 Troubleshooting Prompts: Consolidated troubleshoot_torrent prompt for guided workflows.
  • 😴 Lazy Mode: Reduce token usage by hiding advanced tools until explicitly requested.
  • ⚙️ Configuration: TOML, YAML, JSON, or Environment Variables.
  • 🚀 Transports: Stdio (default) and HTTP (SSE with optional token auth).
  • 📚 Resources: Scoped resources for all instances (e.g., qbittorrent://seedbox/torrents).

🛠️ Available Tools

The server exposes the following tools to the LLM, categorized by functionality:

🌐 Search

  • search_torrents: Search for torrents using qBittorrent's search engine (waits 5 seconds for results).
  • install_search_plugin: Install a new search plugin (URL).
  • uninstall_search_plugin: Uninstall a search plugin (Name).
  • enable_search_plugin: Enable/Disable a search plugin.
  • update_search_plugins: Update all search plugins.
  • get_search_plugins: List installed search plugins.

🗃️ Torrent Management

  • list_torrents: List all torrents with their status and progress. Supports filtering, sorting, and optional inclusion of properties or files.
  • manage_torrents: Unified tool for multiple torrent actions: pause, resume, reannounce, recheck, set_category, add_tags, remove_tags, set_share_limits, set_speed_limits, toggle_sequential, toggle_first_last_prio, set_force_start, set_super_seeding.
  • add_torrent: Add a new torrent via Magnet URI or HTTP URL.
  • delete_torrent: Delete one or more torrents, optionally deleting downloaded files.
  • cleanup_completed: Remove completed torrents based on minimum ratio or maximum age (days).
  • mass_rename: Rename multiple files in a torrent using a Regex pattern and replacement string.
  • find_duplicates: Group and list torrents with identical names.
  • add_trackers: Add trackers to torrents.
  • edit_tracker: Edit a tracker URL for a torrent.
  • remove_trackers: Remove trackers from torrents.
  • rename_folder: Rename a folder in a torrent.
  • set_file_priority: Set priority for files in a torrent.

🔍 Torrent Inspection

  • inspect_torrent: Comprehensive inspection of a torrent (properties, files, and trackers in one call).
  • get_torrent_files: List all files inside a specific torrent.

🚥 Global Control

  • ban_peers: Ban a list of peers (host:port, pipe-separated).
  • set_app_preferences: Update application preferences using a JSON string.

🏷️ Categories & Tags

  • get_categories: List all available categories.

🛜 RSS Management

  • add_rss_feed: Add a new RSS feed.
  • get_rss_feeds: List all RSS feeds and their items.
  • set_rss_rule: Create or update an RSS auto-download rule.
  • get_rss_rules: List all RSS auto-download rules.
  • move_rss_item: Move an RSS item (feed or folder).

🧰 Utility Tools

  • wait_for_torrent_status: Poll a torrent until it reaches a desired state (e.g., "uploading") or timeout. Useful for sequential automation without constant polling from the agent.

📜 System Logs

  • get_main_log: Retrieve the main application log (filter by severity).
  • get_peer_log: Retrieve the peer connection log.

🖥️ System Tools

  • get_system_info: Comprehensive system information (transfer speeds, preferences, version, and build info in one call).
  • shutdown_app: Shutdown the qBittorrent application.
  • show_all_tools: Enable all available tools when running in --lazy mode.

📚 Resources

The server exposes the following resources, scoped by instance name:

  • qbittorrent://{instance}/torrents: Live list of all torrents (JSON).
  • qbittorrent://{instance}/transfer: Global transfer statistics and limits (JSON).
  • qbittorrent://{instance}/categories: List of all defined categories (JSON).

And templates for deep inspection:

  • qbittorrent://{instance}/torrent/{hash}/properties: Comprehensive metadata.
  • qbittorrent://{instance}/torrent/{hash}/files: File structure and individual progress.
  • qbittorrent://{instance}/torrent/{hash}/trackers: Tracker status and messages.

⚙️ Installation

Homebrew

brew tap nicholaswilde/tap
brew install qbittorrent-mcp-rs

From Source

git clone https://github.com/nicholaswilde/qbittorrent-mcp-rs.git
cd qbittorrent-mcp-rs
cargo build --release

The binary will be at target/release/qbittorrent-mcp-rs.

🔧 Configuration

Configuration is loaded from config.{toml,yaml,json} in the current directory, or via CLI arguments.

Example config.toml

qbittorrent_host = "localhost" # or https://your-instance.com
# qbittorrent_port = 8080      # Optional. Defaults to 80 for http, 443 for https.
qbittorrent_username = "admin"
qbittorrent_password = "password"
server_mode = "stdio"          # or "http"
lazy_mode = false              # or true to hide complex tools initially
no_verify_ssl = false          # or true to disable SSL verification
polling_interval_ms = 2000     # Optional. Interval for proactive notifications (default: 2000ms)
# http_auth_token = "secret"   # Optional token for HTTP mode

Environment Variables

Environment variables override configuration file settings. Use _ (single underscore) after the QBITTORRENT prefix, and __ (double underscore) as a separator for nested fields.

  • QBITTORRENT_SERVER_MODE: stdio or http
  • QBITTORRENT_LAZY_MODE: true or false
  • QBITTORRENT_HTTP_AUTH_TOKEN: Token for HTTP mode.
  • QBITTORRENT_LOG_LEVEL: error, warn, info, debug, trace.
  • QBITTORRENT_POLLING_INTERVAL_MS: Polling interval in milliseconds.

Single Instance:

  • QBITTORRENT_HOST: Host address.
  • QBITTORRENT_PORT: Port number.
  • QBITTORRENT_USERNAME: Username.
  • QBITTORRENT_PASSWORD: Password.

Multiple Instances: Use the QBITTORRENT_INSTANCES__<index>__<field> pattern:

  • QBITTORRENT_INSTANCES__0__NAME=local
  • QBITTORRENT_INSTANCES__0__HOST=localhost
  • QBITTORRENT_INSTANCES__1__NAME=seedbox
  • QBITTORRENT_INSTANCES__1__HOST=seedbox.example.com

CLI Arguments

CLI arguments override configuration file settings.

./qbittorrent-mcp-rs --help
  • --config <path>: Path to configuration file.
  • --qbittorrent-host <host>: qBittorrent Web UI host (supports http:// and https://).
  • --qbittorrent-port <port>: qBittorrent Web UI port.
  • --qbittorrent-username <user>: Username.
  • --qbittorrent-password <pass>: Password.
  • --server-mode <mode>: stdio or http.
  • --lazy: Enable lazy mode (shows only essential tools initially to save tokens).
  • --no-verify-ssl: Disable SSL certificate verification (insecure).
  • --http-auth-token <token>: Authentication token for HTTP mode.
  • --polling-interval-ms <ms>: Polling interval for notifications (ms).
  • --log-level <level>: Log level (error, warn, info, debug, trace).
  • --log-file-enable: Enable logging to a file.
  • --log-dir <dir>: Log file directory.
  • --log-filename <name>: Log filename prefix.
  • --log-rotate <strategy>: Log rotation strategy (daily, hourly, never).

💻 Usage

Stdio Mode (Default)

Use with an MCP client (e.g., Claude Desktop, Zed, or another MCP-compliant tool).

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "qbittorrent": {
      "command": "/path/to/qbittorrent-mcp-rs",
      "args": [
        "--qbittorrent-host", "localhost",
        "--qbittorrent-port", "8080",
        "--qbittorrent-username", "admin",
        "--qbittorrent-password", "adminadmin"
      ]
    }
  }
}

HTTP Mode

./qbittorrent-mcp-rs --server-mode http

Server will listen on port 3000.

  • SSE Endpoint: http://localhost:3000/sse
  • Message Endpoint: http://localhost:3000/message

🛠️ Development

Code Coverage

To generate local code coverage reports, ensure you have cargo-llvm-cov installed:

cargo install cargo-llvm-cov

Run the following command to execute tests and generate a console summary along with a lcov.info file:

task coverage

The lcov.info file is compatible with IDE extensions like VS Code Coverage Gutters.

Reporting to Coveralls.io

To upload coverage data to Coveralls.io, set your repository token and run the upload task:

export COVERALLS_REPO_TOKEN=your_token_here
task coverage:upload

Release Management

This project includes a gemini-cli command to help generate GitHub release summaries based on your local git log.

# Summarize changes between the latest two tags (automatic)
gemini release:summary

# Summarize changes for a specific range or tag
gemini release:summary --range v0.3.2..v0.3.3

Secrets Management

The project uses SOPS for encrypting sensitive files like .env.

  • Encrypt: task encrypt (requires .env)
  • Decrypt: task decrypt (requires .env.enc)

🔍 Troubleshooting

Connection & Authentication Issues

  • 401 Unauthorized: Ensure your username and password are correct. If running qBittorrent 4.6.1+ or 5.x, ensure WebUI\HostHeaderValidation=false is set in your qBittorrent.conf if you are accessing it via a custom hostname or reverse proxy.
  • CSRF Protection: If you encounter 403 Forbidden errors during login, ensure WebUI\CSRFProtection=false is set in your configuration, or that the server's Origin and Referer headers (handled automatically by this server) match the expected host.
  • Docker Networking: If running the MCP server outside of Docker and qBittorrent inside, use the host's IP address or localhost (if ports are mapped). If both are in Docker, use the container name as the host.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

⚖️ License

​​Apache License 2.0

✍️ Author

​This project was started in 2026 by Nicholas Wilde.

About

🧲 A qBittorrent MCP server written in Rust 🤖

Topics

mcpmcp-serverqbittorentrustrust-lang

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

6 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Sponsor this project

Packages

Used by

Contributors

Languages