aria2-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aria2-mcp download https://example.com/ubuntu-24.04.iso"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
aria2-mcp
A Model Context Protocol (MCP) server for the aria2 download manager. It exposes aria2's JSON-RPC API as a small, focused set of MCP tools so an agent can queue, inspect, pause, resume and remove downloads.
Features
Speaks the MCP stdio transport, so it works with any MCP-compatible client.
Talks to aria2 over its JSON-RPC interface, including
--rpc-secretauthentication.Strict input validation and structured error reporting.
No runtime dependencies beyond the official MCP SDK.
Fully typed, linted, formatted and unit tested.
Related MCP server: fieldcure-mcp-essentials
Requirements
Node.js 20 or newer.
A reachable aria2 RPC endpoint. Start aria2 with RPC enabled:
aria2c --enable-rpc --rpc-listen-port=6800 --rpc-secret=your_secretInstallation
Use it straight from GitHub without cloning:
npx -y github:iavjkae/aria2-mcpOr install it globally:
npm install -g github:iavjkae/aria2-mcp
aria2-mcpConfiguration
Configuration is read from the environment. The server never ships with a default endpoint and never writes credentials to disk.
Variable | Required | Default | Description |
| yes | — | Full JSON-RPC endpoint, e.g. |
| no | — | Value passed to |
| no |
| Per-request timeout in milliseconds |
ARIA2_RPC_URL must use http or https and must not embed credentials; a value like
http://user:pass@127.0.0.1/jsonrpc is rejected on purpose.
MCP client configuration
{
"mcpServers": {
"aria2": {
"command": "npx",
"args": ["-y", "github:iavjkae/aria2-mcp"],
"env": {
"ARIA2_RPC_URL": "http://127.0.0.1:6800/jsonrpc",
"ARIA2_RPC_SECRET": "your_secret"
}
}
}
}Tools
Tool | Description |
| Queue one or more URIs and return the new GID |
| List active, waiting or stopped downloads |
| Return the full status record for a GID |
| Pause a download |
| Resume a paused download |
| Remove a download and purge its result |
| Aggregate speeds and queue counters |
| aria2 version and compiled features |
Detailed schemas live in docs/tools.md.
Security
Credentials come from the environment only; nothing is committed or logged.
The RPC secret is sent as the standard
token:<secret>parameter and is never echoed back in tool output or error messages.URLs containing embedded credentials are rejected at startup.
test/no-secrets.test.tsfails the build if an endpoint or secret is ever committed.
Development
npm install
npm run lint # ESLint (type-aware)
npm run format # Prettier
npm run typecheck # tsc --noEmit
npm run test # Vitest
npm run test:coverage
npm run build # emits dist/An opt-in integration test runs against a real instance:
ARIA2_RPC_URL=http://127.0.0.1:6800/jsonrpc npm testLicense
Available Tools
8 toolsaria2_add_uriAdd URI downloadA
Queue one or more download URIs (HTTP, HTTPS, FTP, SFTP or magnet links) and return the new GID.
Inputs: uris (required), dir, out, header.
aria2_get_versionaria2 versionA
Return the aria2 version and the features it was built with.
Inputs: no named parameters.
aria2_global_statGlobal statisticsB
Return aggregate download and upload speeds plus queue counters.
Inputs: no named parameters.
aria2_listList downloadsA
List downloads by state. all returns active, waiting and stopped lists in one response.
Inputs: state.
aria2_pausePause downloadB
Pause an active or waiting download.
Inputs: gid (required).
aria2_removeRemove downloadB
Remove a download and purge its result entry. Set force to interrupt checksum verification.
Inputs: gid (required), force.
aria2_statusDownload statusA
Return the full status record of a single download.
Inputs: gid (required).
aria2_unpauseResume downloadC
Resume a paused download.
Inputs: gid (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct aria2 operation: add, remove, pause, unpause, list, status, global_stat, and get_version. Collection vs. single-download vs. aggregate reporting tools are clearly separated by their descriptions.
All tools share the aria2_ prefix and snake_case formatting, which is highly consistent. However, the verb/noun pattern is mixed: some are verbs (remove, pause, unpause, list), some are noun-only (status, global_stat), and some are verb_noun (add_uri, get_version).
Eight tools is well-scoped for an aria2 download management server. Each tool covers a core, non-redundant operation without excessive surface area.
The surface covers the core download lifecycle: add, pause, resume, remove, and query status/list/aggregate stats. Minor gaps exist for update/configuration operations (e.g., changing download or global options, session management) that agents could work around or that may be out of scope.
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
All 20 YourAITools agent APIs in one MCP server. Most tools free; pay with credits or x402.
Agent-native catalogue of Baseframe Labs dev tools and MCP servers.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA download tool for AI agents that wraps aria2 with safety rules and MCP server support, enabling reliable downloads without false positives.1MIT
- AlicenseNot gradedqualityCmaintenanceProvides 20 essential tools including HTTP requests, web search, file I/O, shell commands, and persistent memory for any MCP client, with zero configuration required.MIT
- AlicenseAqualityCmaintenanceMCP server exposing qBittorrent's WebUI API v2 as tools, enabling LLMs to manage torrents, categories, tags, RSS feeds, search plugins, and application settings.903MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP-capable AI agents to queue, monitor, probe, pause, resume, cancel, and speed-limit downloads, grab links from web pages, and manage download categories through a Windows download manager.MIT