通过脚本、仪表盘或命令行来操控
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 版本。仅支持更早版本的客户端会收到明确的提示,而不是悄无声息地失败。
命令行
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 链接交给核心,把整个配置档案放在外置硬盘上,或将客户端融入智能家居——无需再去抓取那些为人类设计的网页。