Aria2 MCP Rs

：file_folder:aria2 MCP服务器（Rust）：机器人：

\[！警告\] 该项目目前正在积极开发中（v0.1.25） 可生产的。功能可能会发生变化，可能会发生重大变化，恕不另行通知。 使用此MCP服务器的风险由您自行承担。

该项目是一个高性能的模型上下文协议（MCP）服务器，用于 咏叹调2，用Rust构建。它为LLM提供了一个全面的界面，通过以下方式监视和管理下载 交互式工具, 只读资源, 上下文提示，以及 实时通知.

：zap：快速入门

1. 先决条件：确保你有 咏叹调2 已安装并在启用RPC的情况下运行(aria2c --enable-rpc).
2. 配置：复制示例配置并使用aria2详细信息进行编辑：

   cp config.toml.example config.toml

1. 跑：使用 cargo 要启动服务器，请执行以下操作：

   cargo run --release

*默认情况下，服务器在 工作室 模式，非常适合当地融合。*

核心建筑特征

• 双重运输实施： 支持两者 工作室 用于本地集成（例如，Claude Desktop）和 HTTP/SSE 用于远程、网络可访问的客户端。
• 功能工具分组： 将细粒度的API动作整合到逻辑管理工具中（例如。， manage_downloads, monitor_queue)以最小化令牌使用并优化AI上下文窗口。
• 多实例支持： 使单个MCP服务器能够同时监视和管理多个aria2实例。
• 严格的文件系统沙盒： 提供对下载目录的安全访问，并防止路径遍历。
• 自动模式验证： 工具使用一个强大的注册表系统，该系统具有基于JSON模式的自动输入验证功能。

已实施的工具

服务器提供了几个用于管理和监视aria2的高级工具：

• manage_downloads：添加、暂停、恢复和删除单个下载。
• manage_all_instances：同时对所有配置的实例执行批量操作（暂停、恢复、清除）。
• bulk_manage_downloads：同时对多个下载执行操作（暂停、恢复、删除）。
• monitor_queue：获取活动、等待和停止下载的实时状态，以及全局统计数据。
• search_downloads：使用子字符串或按文件名、URI、跟踪器URL或状态查找特定下载 正则表达式 过滤器。
• check_health：识别停滞的下载和潜在的队列问题（例如，磁盘空间不足）。
• manage_torrent：管理BitTorrent特定的设置，如获取对等体、选择文件和添加/更新跟踪器。
• schedule_limits：定义带宽速度配置文件，并按计划自动激活它们。
• organize_completed：根据规则（扩展名或模式）自动将已完成的下载移动到目标目录。
• inspect_download：获取特定下载的详细技术元数据、文件列表或URI。
• list_download_files：列出相对于下载目录的指定路径内的文件和目录（严格沙盒）。
• configure_aria2：动态查看和修改全局或每次下载的aria2设置。
• purge_policy：查看或更新自动队列清除策略。
• add_rss_feed：使用可选的关键字或正则表达式过滤器添加新的RSS提要进行监视。
• list_rss_feeds：列出当前监视的所有RSS源及其配置。
• manage_tools：（仅限懒惰模式）启用或禁用单个工具以优化令牌使用。

已实施资源

除了工具，服务器还为直接上下文公开了几个只读资源。所有资源都以某种方式返回数据 多实例格式，同时提供所有已配置的aria2实例的状态：

• aria2://status/global：所有实例的实时全局统计数据（速度、计数）。
• aria2://downloads/active：当前活动下载列表及其GID和进度。
• aria2://logs/recent：应用程序日志的最后N行（可用于调试连接问题）。

实施提示

提示为常见任务提供结构化的交互模板：

• diagnose-download：通过特定下载指导您诊断问题（接受可选 gid)或者整个队列。
• optimize-schedule：通过分析当前设置，帮助您查看和优化带宽计划。

实时通知

服务器支持通过aria2的WebSocket流进行实时通知（目前支持 工作室 运输）。服务器主动从以下位置广播事件 所有已配置的实例 连接到MCP客户端：

• download_start：下载开始时触发。
• download_pause：下载暂停时触发。
• download_stop：下载停止时触发。
• download_complete：下载完成时触发。
• download_error：下载失败时触发。
• bt_download_complete：当BitTorrent下载完成时触发。

技术栈和组件

• 工具注册表： 一种用于注册和执行具有严格输入的工具的模块化系统。
• 动态配置： 使用 config crate用于合并CLI参数、环境变量和配置文件（TOML、YAML、JSON）中的设置。
• 异步运行时： 建立在 tokio，利用后台任务进行高效的I/O和实例管理。
• API系列化（&S）： 杠杆 axum 用于网络传输和 serde/serde_json 用于MCP消息处理。

多实例管理

服务器可以同时管理多个aria2实例。

目标实例

所有工具都接受可选 instance 参数（整数），通过配置中的索引来定位特定实例（默认为 0).

配置

您可以在中定义多个实例 config.toml，通过环境变量，或直接通过命令行参数。

命令行

使用可重复 -i/--instance 标志：

aria2-mcp-rs --instance name=local,url=http://localhost:6800/jsonrpc --instance name=remote,url=http://192.168.1.10:6800/jsonrpc,secret=token

环境变量

使用配置加载器支持的索引格式：

# Instance 0 (Primary)
export ARIA2_MCP__INSTANCES__0__NAME="primary"
export ARIA2_MCP__INSTANCES__0__RPC_URL="http://127.0.0.1:6800/jsonrpc"

# Instance 1 (Secondary)
export ARIA2_MCP__INSTANCES__1__NAME="remote-box"
export ARIA2_MCP__INSTANCES__1__RPC_URL="http://192.168.1.10:6800/jsonrpc"
export ARIA2_MCP__INSTANCES__1__RPC_SECRET="your-secret"

💾 持久自定义规则

通过MCP工具对自定义规则（如带宽计划和文件组织规则）所做的更改会自动持久化到本地状态文件中(aria2_mcp_state.json)在当前工作目录中。

当服务器启动时，它会自动加载这些持久规则，并将其与您的数据库中定义的规则合并 config.toml，确保LLM添加的任何规则在服务器重启后仍然有效。

：timer_clock：带宽调度

服务器可以根据时间表自动调整aria2带宽限制。您可以在中定义配置文件和计划 config.toml:

[bandwidth_profiles.work]
max_download = "500K"
max_upload = "50K"

[bandwidth_profiles.night]
max_download = "0" # Unlimited
max_upload = "0"

[[bandwidth_schedules]]
day = "daily"
start_time = "09:00"
end_time = "17:00"
profile_name = "work"

[[bandwidth_schedules]]
day = "daily"
start_time = "22:00"
end_time = "06:00"
profile_name = "night"

：废纸篓：自动队列清理

服务器可以在下载达到一定年龄后自动从aria2队列中删除已完成或错误的下载。

配置

您可以在中启用和配置清除行为 config.toml:

[purge_config]
enabled = true
interval_secs = 3600  # Run check every hour
min_age_secs = 86400  # Purge downloads older than 24 hours
excluded_gids = ["gid1", "gid2"] # Optional: GIDs to never purge

：shield：自动错误恢复

该服务器包括内置的弹性功能，用于处理瞬态下载故障：

• 智能检索：使用指数回退自动重试因暂时错误（例如网络超时、连接被拒绝）而失败的下载。
• 跟踪器注入：对于安装了0个对等端的BitTorrent下载，服务器可以自动从公共列表中获取和注入额外的跟踪器，以帮助查找对等端。

您可以在中配置这些功能 config.toml:

[retry_config]
max_retries = 3
initial_backoff_secs = 5
tracker_injection_enabled = true
tracker_list_url = "https://trackerslist.com/all.txt"

：rss:rss源监控

服务器可以自动监视RSS提要，并根据过滤器向下载队列添加新项目。您可以通过MCP工具管理提要，也可以在 config.toml:

[[rss_config.feeds]]
name = "My Linux ISOs"
url = "https://example.com/rss"
filters = ["ubuntu", "debian"] # Matches any keyword (case-insensitive)

[[rss_config.feeds]]
name = "Important Security Updates"
url = "https://example.com/security"
filters = ["regex:^CVE-2026-.*"] # Matches a regular expression

：open_file_folder：自动文件组织

服务器可以根据用户定义的规则自动将完成的下载移动到目标目录。规则可以按扩展名或正则表达式模式匹配文件。

配置

在中定义组织规则 config.toml:

[[organize_rules]]
name = "Movies"
extensions = ["mp4", "mkv", "avi"]
targetDir = "/mnt/media/movies"

[[organize_rules]]
name = "Linux ISOs"
pattern = "ubuntu-.*\\.iso"
targetDir = "/mnt/storage/isos"

*注： targetDir 如果不存在，将自动创建。*

：movie_camera：媒体顺序下载

服务器支持BitTorrent任务的顺序下载。这允许您在媒体文件仍在下载时开始预览或流媒体文件，确保按顺序下载。

用法

• 新下载：通过添加torrent时 manage_downloads，设置 sequential 旗帜到 true.
• 现有下载：使用 manage_torrent 工具与 toggleSequential 行动与设定 sequential 到 true 或 false.

：package：安装

自制（macOS/Linux）

brew install nicholaswilde/tap/aria2-mcp-rs

：hammer_and_wrench：建设与发展

基于任务的工作流

利用 Taskfile.yml 规范开发任务：

# Build in release mode
task build

# Run tests and lints
task check

质量保证

• Docker集成测试： 验证与aria2容器的真实交互。
• 单元测试： 核心逻辑的全面测试套件。
• 发布优化： 链路时间优化（LTO）和符号剥离，以实现最小的二进制大小。

：火箭：用途

服务器可以通过命令行参数、环境变量或 config.toml 当前目录中的文件。

命令行界面

./target/release/aria2-mcp-rs --rpc-url "http://127.0.0.1:6800/jsonrpc" --rpc-secret "your-secret"

配置选项

：balance_scale:许可证

Apache许可证2.0

：writing_hand：作者

该项目于2026年启动 尼古拉斯·王尔德.