REST API、MCP 与命令行

通过脚本、仪表盘或命令行来操控

eMule Qt 保留了经典的 Web 界面,并在其旁新增了完善的 JSON REST API、面向 AI 助手的 MCP 端点以及命令行控制,让客户端可以与其他软件交互。

REST API

内置 Web 服务器提供 /api/v1/*——包括连接状态与连接/断开、搜索与搜索结果、下载列表(可对每个传输任务暂停、恢复、取消和预览)、上传、共享文件、服务器、好友、统计,以及通过 GET 和 PATCH 读写的偏好设置。请求通过 API 密钥进行认证,服务器也可以通过 HTTPS 运行。

Web 界面与 API 是相互独立的开关:您可以只提供 JSON API 而完全不开放 HTML 界面,反之亦然。默认端口为 4711,如有需要,端口映射层会为您转发该端口。

MCP:让 AI 助手操控您的客户端

eMule Qt 支持模型上下文协议(Model Context Protocol,MCP),这是 AI 助手与其他程序协作所采用的开放标准。启用后,Claude 等助手即可查看并操作您的客户端:“还有什么在下载?”、“在 Kad 中搜索这个,并把来源最多的结果加入队列”、“暂停“视频”分类中的所有任务”。

助手可以做什么

守护进程提供 51 个工具,都是按助手的实际需求挑选的:

  • 状态——连接、Kademlia、防火墙与端口状态、统计和日志。
  • 搜索——发起搜索、读取结果并直接从结果中下载。结果附带虚假文件判定,助手会被告知哪些结果值得怀疑及其原因。
  • 下载——列出、添加、暂停、恢复、停止和取消,查看下载的来源,清除已完成项。
  • 服务器与 Kad——列出、添加、移除并连接服务器,启动和停止 Kad,导入节点。
  • 共享——共享文件和目录、上传与上传队列。
  • Usenet——Usenet 队列、通过 URL 添加 NZB,以及对发布项执行操作。
  • 分类与偏好设置——读取它们,并在模式声明可写的地方进行修改。

与 REST API 使用同一套代码

MCP 并不是第二套实现。每个工具都是同一张操作表中的一项,而该表同时生成上文的 REST API,因此工具调用的校验与执行方式和对应的 HTTP 请求完全一致:未知字段或超出范围的值会被拒绝,而不是被忽略。具有破坏性的调用——取消下载、移除发布项——必须带上 "confirm": true。关闭守护进程则根本不是一个工具。

由您开启,未开启则保持关闭

  • 默认关闭——在您启用之前,不会有任何东西监听助手的连接。
  • 每次调用都需 API 密钥——与 REST API 使用同一密钥,服务器也可以通过 HTTPS 运行。
  • 只读模式——一个开关,助手就只能使用不会更改任何内容的工具。它可以查看一切,却无法改动任何东西。
  • 杜绝恶意网页——来自未获允许的浏览器源的请求会被拒绝。
  • 不暴露机密——凭据、API 密钥以及任何指向程序或证书的内容,都无法通过偏好设置工具读取或设置。

连接助手

端点为 Web 服务器端口(默认 4711)上的 /mcp,采用可流式传输的 HTTP。支持 HTTP 的客户端可直接连接——以 Claude Code 为例:

claude mcp add --transport http emuleqt http://localhost:4711/mcp --header "Authorization: Bearer <api key>"

只能启动本地程序的客户端,则使用小型桥接程序 emuleqt-mcp,每个下载包中都附带它,与守护进程放在一起。它会从您的本地配置中读取端口和密钥,因此无需输入任何内容:

{ "mcpServers": { "emuleqt": { "command": "/path/to/emuleqt-mcp" } } }

该桥接程序也可以连接另一台机器上的守护进程:

emuleqt-mcp --url https://nas.example:4711/mcp --api-key <key>

eMule Qt 实现的是 MCP 2026-07-28 版本。仅支持更早版本的客户端会收到明确的提示,而不是悄无声息地失败。

.:启用方法
选项 → Web 界面 → “为 AI 助手启用 MCP 服务器”,旁边就是“只读”选项。API 密钥位于同一页面。守护进程启动时会在日志中记录端点地址。

命令行

eMule Qt 附带三个程序,它们都支持命令行选项:图形界面 emuleqt、核心 emulecored 和 MCP 桥接程序 emuleqt-mcp。每个程序都可以用 --help 打印完整选项列表,用 --version 打印版本。

正在运行的核心可以直接通过 shell 控制,这样就能轻松把 eMule Qt 接入脚本、文件管理器和浏览器处理程序:

emulecored --add-link "ed2k://|file|...|/"
emulecored --add-nzb ~/Downloads/linux-iso.nzb
emulecored --connect
emulecored --disconnect
emulecored --connect-kad

自定义配置文件夹:–config

默认情况下,设置在 Linux 和 macOS 上位于 ~/eMuleQt/Config,在 Windows 上位于 %LOCALAPPDATA%\eMuleQt(便携模式下则是程序旁的 config 文件夹)。--config <dir> 可让 eMule Qt 使用其他位置:

emuleqt --config /media/eMuleQt/Config
  • 配置文件夹中的所有内容都会随之迁移:preferences.yml、服务器列表、Kad 联系人、已知文件、积分、您的用户哈希和密钥、Usenet 提供商以及日志文件。如果该文件夹尚不存在,会自动创建。
  • 图形界面会把自己的 --config 传给它启动的核心,因此两者始终读取同一份设置。
  • Incoming 和 Temp 文件夹是单独的设置。全新的配置文件夹默认使用 ~/eMuleQt/Incoming 和 ~/eMuleQt/Temp;如需一并迁移下载内容,请在选项 → 目录中修改。
  • 每个配置文件夹就是一个独立的配置档案。只要使用不同的端口(TCP、UDP、核心端口 4712 和 Web 端口 4711),两个配置档案就可以并行运行,各有自己的窗口。
  • 发送给正在运行的核心的命令同样支持 --config,因此 emulecored --config /media/eMuleQt/Config --connect 会找到该配置档案对应的核心。

图形界面:emuleqt

选项 作用
ed2k://… file.nzb 添加 ED2K 链接,或将一个或多个 .nzb 文件加入队列。如果 eMule Qt 已使用相同的配置文件夹运行,它们会交给该窗口处理,而不是再打开一个新窗口。
--config <dir> 使用其他配置文件夹(见上文)。
--new-instance 即使此安装和配置文件夹已有窗口在运行,也再打开一个窗口。
--tab <name> 启动时显示指定标签页:kad、servers、transfers、search、shared、messages、irc、statistics、usenet。
--subtab <n> Kad 或传输标签页的子标签页,从 0 开始计数。
--subtab-top <n> 传输标签页上方窗格中的列表:0 下载,1 正在上传,2 正在下载,3 队列中,4 已知客户端。
--options <page> 打开选项对话框并定位到指定页面:general、display、connection、proxy、server、directories、files、notifications、statistics、irc、messages、security、scheduler、webinterface、usenet、indexers、feeds、extended。
--register-file-types 将本程序设为 .nzb 文件的处理程序,然后退出。适合在打包程序的安装后脚本中使用。
--unregister-file-types 移除 .nzb 文件关联,然后退出。
--screenshot <path> 保存窗口(或 --options 页面)的截图,然后退出。--delay <ms> 设置截图前的等待时间,默认 3000。

核心:emulecored

不带命令启动时,emulecored 作为核心运行。带命令启动时,它会把命令发送给已在运行的核心,然后退出。

选项 作用
--add-link <link> 通过 ed2k://|file| 链接添加下载,或应用 ed2k://|httpcache| 配置链接。
--add-nzb <file|url> 从 .nzb 文件或 http(s) URL 将 Usenet 下载加入队列。URL 由核心自行获取,因此只需核心所在机器能够访问即可。
-c, --connect 连接到 ED2K 服务器。
-d, --disconnect 断开与 ED2K 服务器的连接。
--connect-kad 启动 Kademlia。
--disconnect-kad 停止 Kademlia。
--config <dir> 使用其他配置文件夹(见上文)。
--port <port> 图形界面与核心之间的端口,默认 4712。启动时是核心监听的端口;带命令时则是命令要发送到的核心端口。
--hold-connect 启动后先不连接,直到图形界面的首次启动向导选定端口。图形界面会自动设置此项。

MCP 桥接程序:emuleqt-mcp

该桥接程序将 AI 助手连接到核心(参见上文的 MCP)。不带选项时,它会从本地配置读取端口和 API 密钥。

选项 作用
--config <dir> 从其他配置文件夹读取端口和 API 密钥。
--url <url> 连接到其他位置的核心,例如 http://192.168.1.10:4711/mcp。
--api-key <key> 要使用的 API 密钥。默认:先取 $EMULEQT_API_KEY,再取本地配置。
--insecure 接受自签名的 HTTPS 证书。

意义何在

构建您自己的仪表盘,让助手管理您的下载,绘制传输历史曲线,从系统任意位置把 ED2K 链接交给核心,把整个配置档案放在外置硬盘上,或将客户端融入智能家居——无需再去抓取那些为人类设计的网页。

 

返回所有功能