jdownloader-mcp

An MCP server that lets an agent drive a local JDownloader 2 through its entire download lifecycle — add links / containers, watch the linkgrabber resolve them, move them to the queue, set priority, force-start, track progress, inspect download/extract directories, and clean up.

It exists for the one download workload the shell can't already do: premium hosters, one-click hosters, .dlc/.crypt containers, and captcha-gated folder links. (Plain URLs and video are better served by aria2c / yt-dlp.)

Thin wrapper over myjdapi; built on the mcp 1.x FastMCP API.

Status: v0.1.0 — untested against a live JDownloader. Passes 52 mocked unit tests and a real MCP stdio handshake, but the end-to-end lifecycle (smoke_test.py) has not yet been run against a live JD2. Treat as a pre-release; verify before relying on it.

Lifecycle

add_links / add_container ─▶ LINKGRABBER ─(move_to_downloads)─▶ DOWNLOADS ─▶ extract ─▶ remove
                            list_linkgrabber                    list_downloads / force_start / wait_for

Item IDs (uuid) come from the list_* tools; most tools take package_ids / link_ids plus a stage (linkgrabber | downloads).

Tools

add_links · add_container · list_linkgrabber · list_downloads · status · wait_for · move_to_downloads · control_downloads · force_start · set_priority · set_enabled · get_directories · set_download_dir · set_extraction · remove · reset · raw_action (generic passthrough to any JD API endpoint not wrapped above).

Setup

1. In JDownloader: Settings → My.JDownloader, sign in / link the device, note its device name.
2. Configure creds:

   cp .env.example .env   # then edit .env
   

3. Install deps (already done if you used uv):

   uv sync
   

Verify

uv run pytest                     # mocked unit tests (no JD needed)
uv run python smoke_test.py       # live end-to-end against your JD2 (uses .env)

The smoke test walks the whole lifecycle with a tiny file and cleans up. It SKIPs cleanly if the env vars aren't set.

Register with Claude Code

claude mcp add jdownloader -- uv run --directory E:/SWE-Pioneers/projects/jdownloader-mcp jdownloader-mcp

or add to your MCP client config (stdio):

{
  "mcpServers": {
    "jdownloader": {
      "command": "uv",
      "args": ["run", "--directory", "E:/SWE-Pioneers/projects/jdownloader-mcp", "jdownloader-mcp"]
    }
  }
}

The server reads MYJD_EMAIL / MYJD_PASSWORD / MYJD_DEVICE from .env (or the environment).

Docs

• docs/2026-08-01-jdownloader-mcp-design.md — design spec.
• docs/myjdapi-api-reference.md — exact installed-API reference the code targets.

License

MIT — see LICENSE.