Aria2 Agent MCP Server

@Rehui-2006

代码仓库主页

基本信息

许可证

MIT

传输方式

stdio

作者

Rehui-2006

提交者

Rehui

关于 Aria2 Agent MCP Server

AI Agent-first download tool built on aria2. Forces file-allocation=none, uses RPC tellStatus for reliable completion detection. MCP compatible, zero dependencies.

#aria2#download #mcp #ai-agent #python

Aria2 Agent MCP Server 配置

使用下面的配置,将此服务器添加到你的 MCP 客户端。

{
  "mcpServers": {
    "aria2-agent": {
      "command": "python",
      "args": [
        "-m",
        "aria2cli",
        "mcp"
      ]
    }
  }
}

Aria2 Agent MCP Server 工具

工具列表暂未提供

当前收录暂时没有可展示的工具列表，不代表服务没有工具。请查阅项目文档了解支持的能力。

工具是从 README 中自动提取的。维护者可以在 ## Tools 标题下列出工具,即可填充这部分内容。

概览

What is Aria2 Agent?

Aria2 Agent is a CLI tool and MCP (Model Context Protocol) server that wraps aria2’s JSON-RPC interface with safety rules for AI Agents. It solves the false-positive completion problem caused by aria2’s default preallocation, giving agents a reliable download status via pure JSON output. It is built for developers and AI agent users who need trustworthy, large-file downloads.

How to use Aria2 Agent?

Install with pip install aria2-agent or download the single-file aria2cli.py. Ensure Python 3.8+ and aria2c are in PATH. Start the RPC daemon once per session (python aria2cli.py start --dir ~/Downloads), then submit downloads with python aria2cli.py add <URL> --dir <path> --out <file> --wait --timeout 3600. The agent reads the JSON result’s complete field. For MCP integration, run python aria2cli.py mcp and configure the server in Claude Desktop or Cursor/VS Code.

Key features of Aria2 Agent

Forces file-allocation=none to prevent phantom files.
Completion judged via RPC only, never local file size.
Pure JSON output for easy agent parsing.
Built-in 3x retry, resume, and 3600s timeout.
MCP Server mode with 8 tools, zero configuration.
Zero dependencies – pure Python 3.8 standard library.
Cross-platform: Windows, Linux, macOS.
Prevents rule circumvention with forbidden per-task options.

Use cases of Aria2 Agent

Downloading large AI models and datasets with reliable completion reporting.
Automating downloads in AI agent workflows (Claude, GPT, Cursor).
Multi-source mirror downloads with automatic fallback.
Async download management – submit, poll, pause, resume tasks.

常见问题

How is Aria2 Agent different from using `aria2c` directly?

Aria2 Agent solves the false-positive completion problem where `aria2c`’s default preallocation creates a full-size placeholder file before data arrives. Agents checking file size get a false “complete” signal. Aria2 Agent forces `file-allocation=none`, checks completion via RPC only, and outputs clean JSON with a reliable `complete` field. It also enforces 10 architecturally‑enforced iron rules that cannot be bypassed.

What are the dependencies and runtime requirements?

Python 3.8 or higher and `aria2c` in PATH. The base tool has zero external dependencies – it uses only the Python standard library. For MCP Server mode, install with `pip install "aria2-agent[mcp]"`.

Where does my data and configuration live?

The RPC daemon listens only on `127.0.0.1`. The auto-generated RPC secret token is stored in `~/.aria2_agent/state.json`. No data ever leaves your machine. All downloaded files are written to the directory you specify.

Does Aria2 Agent collect telemetry or phone home?

No. The only network connection is to the local aria2 daemon on `127.0.0.1`. There is no telemetry, analytics, update checks, or data collection. The entire source is a single 959‑line file for easy auditing.

What transport and authentication does it use?

Aria2 Agent communicates with the local aria2 daemon via JSON