# REST API, MCP & CLI

Source: https://emule-qt.org/features/rest-api-cli/

## Drive it from a script, a dashboard or a shell

eMule Qt keeps the classic web interface and adds a proper **JSON REST API** next to it, an **MCP endpoint** for AI assistants, and command-line control, so the client is something other software can talk to.

### REST API

The built-in web server exposes `/api/v1/*` — connection state and connect/disconnect, search and search results, the download list with pause, resume, cancel and preview per transfer, uploads, shared files, servers, friends, statistics, and preferences over GET and PATCH. Requests are authenticated with an API key, and the server can run over HTTPS.

The web UI and the API are **independent switches**: you can serve the JSON API without exposing the HTML interface at all, or the other way round. The default port is **4711**, and the port-mapping layer will forward it for you if you ask it to.

## MCP: let an AI assistant drive your client

eMule Qt speaks the **Model Context Protocol** (MCP), the open standard AI assistants use to work with other programs. Switch it on and an assistant such as Claude can look at your client and act on it: “what is still downloading?”, “search Kad for this and queue the result with the most sources”, “pause everything in the Video category”.

### What an assistant can do

The daemon offers **51 tools**, chosen for what an assistant actually needs:

- **Status** — connection, Kademlia, firewall and port state, statistics and the log.
- **Search** — start a search, read the results and download straight from them. Results carry the [fake-file verdict](https://emule-qt.org/features/fake-file-detector/), so the assistant is told which ones to doubt and why.
- **Downloads** — list, add, pause, resume, stop and cancel, see a download’s sources, clear completed.
- **Servers and Kad** — list, add, remove and connect to servers, start and stop Kad, import nodes.
- **Sharing** — shared files and directories, uploads and the upload queue.
- **Usenet** — the Usenet queue, adding an NZB by URL and acting on a release.
- **Categories and preferences** — read them, and change them where the schema says they are writable.

### The same code as the REST API

MCP is not a second implementation. Every tool is an entry of the same operation table that produces the [REST API](https://emule-qt.org/features/rest-api-cli/#rest-api) above, so a tool call is validated and carried out exactly like the matching HTTP request: an unknown field or a value out of range is refused, not ignored. Destructive calls — cancelling a download, removing a release — must say `"confirm": true`. Shutting the daemon down is not a tool at all.

### Yours to open, and closed until you do

- **Off by default** — nothing listens for an assistant until you enable it.
- **API key on every call** — the same key as the REST API, and the server can run over HTTPS.
- **Read-only mode** — one switch, and the assistant is offered only the tools that change nothing. It can look at everything and touch none of it.
- **No drive-by web pages** — a request from a browser origin you have not allowed is refused.
- **No secrets** — credentials, API keys and anything that names a program or certificate cannot be read or set through the preferences tools.

### Connecting an assistant

The endpoint is `/mcp` on the web server’s port (default **4711**), over streamable HTTP. A client that speaks HTTP connects directly — Claude Code, for example:

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

A client that can only start a local program uses the small bridge **emuleqt-mcp**, which ships next to the daemon in every download. It reads the port and the key from your local configuration, so there is nothing to type:

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

The bridge also reaches a daemon on another machine:

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

eMule Qt implements MCP revision **2026-07-28**. A client that only knows an older revision is told so in plain words instead of failing silently.

> **Turn it on**
> 
> **Options → Web Interface →** “Enable MCP server for AI assistants”, with “Read-only” right beside it. The API key is on the same page. The daemon logs the endpoint’s address when it starts.

## Command line

eMule Qt ships three programs, and all of them take command-line options: the GUI `emuleqt`, the core `emulecored`, and the MCP bridge `emuleqt-mcp`. Each one prints its full list with `--help` and its version with `--version`.

A running core can be driven straight from the shell, which makes it easy to wire eMule Qt into scripts, file managers and browser handlers:

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

### Your own config folder: –config

By default the settings live in `~/eMuleQt/Config` on Linux and macOS, and in `%LOCALAPPDATA%\eMuleQt` on Windows (or the `config` folder next to the program in portable mode). `--config <dir>` points eMule Qt somewhere else:

```
emuleqt --config /media/eMuleQt/Config
```

- Everything in the config folder moves with it: `preferences.yml`, the server list, Kad contacts, known files, credits, your user hash and keys, Usenet providers and the log files. The folder is created if it does not exist yet.
- The GUI hands its `--config` on to the core it starts, so both always read the same settings.
- The **Incoming** and **Temp** folders are settings of their own. A fresh config folder starts with `~/eMuleQt/Incoming` and `~/eMuleQt/Temp`; change them in *Options → Directories* to move your downloads as well.
- Each config folder is its own profile. Two profiles can run side by side, each with its own window, as long as they use different ports (TCP, UDP, the core port 4712 and the web port 4711).
- Commands sent to a running core take `--config` too, so `emulecored --config /media/eMuleQt/Config --connect` finds the core of that profile.

### GUI: emuleqt

| Option | What it does |
|---|---|
| `ed2k://…` `file.nzb` | Add an ED2K link, or queue one or more `.nzb` files. If eMule Qt already runs with the same config folder, they are handed to that window instead of opening a second one. |
| `--config <dir>` | Use another config folder (see above). |
| `--new-instance` | Open another window even if one already runs for this install and config folder. |
| `--tab <name>` | Start on a tab: `kad`, `servers`, `transfers`, `search`, `shared`, `messages`, `irc`, `statistics`, `usenet`. |
| `--subtab <n>` | Sub-tab of the Kad or Transfers tab, counted from 0. |
| `--subtab-top <n>` | List in the upper Transfers pane: 0 downloads, 1 uploading, 2 downloading, 3 on queue, 4 known clients. |
| `--options <page>` | Open the Options dialog on a page: `general`, `display`, `connection`, `proxy`, `server`, `directories`, `files`, `notifications`, `statistics`, `irc`, `messages`, `security`, `scheduler`, `webinterface`, `usenet`, `indexers`, `feeds`, `extended`. |
| `--register-file-types` | Make this program the handler for `.nzb` files, then exit. Handy in a packager’s post-install script. |
| `--unregister-file-types` | Remove the `.nzb` association again, then exit. |
| `--screenshot <path>` | Save a screenshot of the window (or of the `--options` page) and exit. `--delay <ms>` sets the wait before it, 3000 by default. |

### Core: emulecored

Started without a command, `emulecored` runs as the core. Started with one, it sends the command to the core that is already running and exits.

| Option | What it does |
|---|---|
| `--add-link <link>` | Add a download from an `ed2k://\|file\|` link, or apply an `ed2k://\|httpcache\|` configuration link. |
| `--add-nzb <file\|url>` | Queue a Usenet download from an `.nzb` file or an http(s) URL. A URL is fetched by the core itself, so it only has to be reachable from the core’s machine. |
| `-c`, `--connect` | Connect to an ED2K server. |
| `-d`, `--disconnect` | Disconnect from the ED2K server. |
| `--connect-kad` | Start Kademlia. |
| `--disconnect-kad` | Stop Kademlia. |
| `--config <dir>` | Use another config folder (see above). |
| `--port <port>` | Port between GUI and core, 4712 by default. On start it is the port the core listens on; with a command it is the core to send it to. |
| `--hold-connect` | Start without connecting until the GUI’s first-start wizard has chosen the ports. The GUI sets this itself. |

### MCP bridge: emuleqt-mcp

The bridge connects AI assistants to the core (see [MCP](https://emule-qt.org/features/rest-api-cli/#mcp) above). Without options it reads the port and API key from the local configuration.

| Option | What it does |
|---|---|
| `--config <dir>` | Read port and API key from another config folder. |
| `--url <url>` | Talk to a core elsewhere, e.g. `http://192.168.1.10:4711/mcp`. |
| `--api-key <key>` | API key to use. Default: `$EMULEQT_API_KEY`, then the local configuration. |
| `--insecure` | Accept a self-signed HTTPS certificate. |

## Why it matters

Build your own dashboard, let an assistant run your downloads, plot your transfer history, hand ED2K links to the core from anywhere on your system, keep your whole profile on an external drive, or fold the client into home automation — without screen-scraping a web page that was designed for humans.

[Back to all features](https://emule-qt.org/features/)

---

Part of eMule Qt. Site index for agents: https://emule-qt.org/llms.txt