nicholaswilde/aria2-mcp-rs repository overview

⁠aria2 MCP Server (Rust)

A high-performance Model Context Protocol (MCP)⁠ server written in Rust that enables Large Language Models (LLMs) to manage and monitor aria2⁠ download instances. This server acts as a secure, context-efficient bridge for autonomous download management, queue monitoring, and automated file organization.

⁠✨ Features

• Multi-Instance Management: Control and target multiple aria2 instances from a single MCP interface.
• Real-time Notifications: Background monitoring of aria2 events with push notifications to MCP clients.
• Smart Error Recovery: Automated detection and diagnosis of download failures with suggested recovery actions.
• Bandwidth Scheduling: Dynamically manage download/upload limits based on scheduled performance profiles.
• Automated File Organization: Rules-based moving and renaming of completed downloads into a structured filesystem.
• Queue Health Monitoring: Background purging of old or failed entries based on customizable retention policies.
• Security & Privacy: Support for sandboxed filesystem access, sensitive data masking, and secure credential handling via environment variables.

⁠🚀 Quick Start

⁠Docker Run

Start the server quickly by providing your aria2 RPC secret and host information:

docker run --rm \
  -e ARIA2_RPC_SECRET="your-secret-token" \
  -e ARIA2_RPC_ENDPOINT="http://localhost:6800/jsonrpc" \
  nicholaswilde/aria2-mcp-rs

⁠Docker Compose

Deploy the MCP server alongside a local aria2 instance:

services:
  mcp-server:
    image: nicholaswilde/aria2-mcp-rs
    environment:
      - ARIA2_RPC_ENDPOINT=http://aria2:6800/jsonrpc
      - ARIA2_RPC_SECRET=${ARIA2_SECRET}
    depends_on:
      - aria2

  aria2:
    image: p3terx/aria2-pro
    # ... standard aria2 configuration ...

⁠🛠 Available Tools

The server exposes several specialized tools to LLMs for advanced management:

• manage_downloads: Add, pause, resume, or remove downloads.
• inspect_download: Get detailed metadata and status for specific GIDs.
• search_downloads: Find downloads using regex patterns on filenames or URIs.
• manage_torrent: Specialized tools for adding and inspecting BitTorrent files.
• configure_aria2: Dynamically update global or session-specific aria2 settings.

⁠🔒 Configuration

The image is highly configurable via environment variables:

• ARIA2_RPC_ENDPOINT: The JSON-RPC URL for your aria2 instance.
• ARIA2_RPC_SECRET: Authentication token for the RPC interface.
• MCP_LOG_LEVEL: Adjust logging verbosity (info, debug, trace).
• ARIA2_MCP_STORAGE_PATH: Path for persistent state and file organization.

Note: This project is currently in active development. Features and tool signatures may change.