Skip to main content
Glama
aria2-mcp
by iavjkae

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.

CI License: MIT Node

Features

  • Speaks the MCP stdio transport, so it works with any MCP-compatible client.

  • Talks to aria2 over its JSON-RPC interface, including --rpc-secret authentication.

  • 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_secret

Installation

Use it straight from GitHub without cloning:

npx -y github:iavjkae/aria2-mcp

Or install it globally:

npm install -g github:iavjkae/aria2-mcp
aria2-mcp

Configuration

Configuration is read from the environment. The server never ships with a default endpoint and never writes credentials to disk.

Variable

Required

Default

Description

ARIA2_RPC_URL

yes

—

Full JSON-RPC endpoint, e.g. http://127.0.0.1:6800/jsonrpc

ARIA2_RPC_SECRET

no

—

Value passed to --rpc-secret; secret and token:secret are both accepted

ARIA2_TIMEOUT_MS

no

30000

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

aria2_add_uri

Queue one or more URIs and return the new GID

aria2_list

List active, waiting or stopped downloads

aria2_status

Return the full status record for a GID

aria2_pause

Pause a download

aria2_unpause

Resume a paused download

aria2_remove

Remove a download and purge its result

aria2_global_stat

Aggregate speeds and queue counters

aria2_get_version

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.ts fails 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 test

License

MIT

Available Tools

8 tools
aria2_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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).

    Tool Count5/5

    Eight tools is well-scoped for an aria2 download management server. Each tool covers a core, non-redundant operation without excessive surface area.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      A download tool for AI agents that wraps aria2 with safety rules and MCP server support, enabling reliable downloads without false positives.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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
    • A
      license
      A
      quality
      C
      maintenance
      MCP server exposing qBittorrent's WebUI API v2 as tools, enabling LLMs to manage torrents, categories, tags, RSS feeds, search plugins, and application settings.
      90
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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