HMCL MCP Server

MCP (Model Context Protocol) server that lets AI agents drive HMCL (Hello Minecraft! Launcher, https://hmcl.huangyuhui.net) programmatically: install Minecraft versions, search/download/import modpacks (Modrinth + CurseForge), and launch/stop the game.

HMCL has no command line interface (no --launch, no --import, no headless mode), so this project injects a small javaagent into a headless HMCL JVM and drives HMCL's core classes directly. Modpack search/download/install all run through HMCL's own addon repositories inside the agent (Modrinth, and CurseForge with HMCL's embedded API key — no user key needed); listing installed versions/modpacks is a local filesystem scan.

Architecture

┌──────────────────────────────┐   stdio (JSON-RPC only)   ┌────────────────────────────────┐
│  MCP client / AI agent       │ ◀────────────────────────▶ │  Node MCP server (this repo)   │
└──────────────────────────────┘                            └───────────────┬────────────────┘
                                                      filesystem scans      │ HTTP JSON API
                                                <workdir>/versions/,        │ 127.0.0.1:<port>
                                                mcpacks/ (search/download)  │ X-HMCL-Agent-Token
                                                                             ▼
                                                              ┌────────────────────────────────┐
                                                              │  Headless HMCL JVM              │
                                                              │  java -javaagent:hmcl-agent.jar │
                                                              │  -Dhmcl.gameDir=<workdir> …      │
                                                              │  -cp HMCL.jar;javafx-*.jar       │
                                                              │  hmcl.agent.AgentMain            │
                                                              └────────────────────────────────┘

• Node MCP server (src/, TypeScript, stdio transport): registers 13 tools, drives HMCL's own Modrinth/CurseForge modpack repositories for search/download/install, scans <workdir>/versions/ on disk for installed versions and modpacks, and talks to the agent over loopback HTTP.

• Java agent (agent/, compiled by npm run build:agent): injected into HMCL with -javaagent; initializes HMCL core headlessly (SettingsManager.init() → DownloadProviders.init() → Accounts.init()) and exposes a loopback HTTP JSON API (/status, /versions/install, /modpack/install, /launch, /launch/stop, /shutdown) on 127.0.0.1:<port>. A non-daemon HTTP thread keeps the JVM alive.

• No launcher GUI: the HMCL window never opens. When you launch the game, the game window itself opens normally (the game is a separate child process).

HMCL-compatible directory layout inside the workdir: versions/<id>/, libraries/, assets/, mcpacks/ (downloaded pack files), hmcl/ (HMCL.jar + hmcl-agent.jar + javafx jars), .hmcl/ (HMCL 3.16+ workspace config).

Requirements

• Node.js 18+ (24 recommended) — MCP SDK 1.30.0, npm install

• JDK 17+ with javac (21 recommended) — HMCL itself requires Java 17; javac is needed to compile the agent jar

• Internet access on first run (HMCL jar, javafx jars, Minecraft versions/libraries/assets)

Tools (13)

All handlers return structured data on success and an error message on failure (MCP isError result) — they never crash the server.

Quick start

npm install          # install dependencies
npm run build        # compile the MCP server → dist/
npm run build:agent  # download javafx jars + compile agent/build/hmcl-agent.jar (javac required)

Register the server in your MCP client:

{
  "mcpServers": {
    "hmcl-mcp": {
      "command": "node",
      "args": ["D:/ProjectDir/AgentFarm/HMCL-MCP/dist/index.js"]
    }
  }
}

Environment variables can be set in the client's env object, in your shell, or via a .env file — see .env.example and docs/setup.md.

Environment variables

Typical agent workflows

1. Modpack: search → install → launch

   search_modpacks(query: "fabulously optimized") → get_modpack(id: "fabulously-optimized") → install_modpack(id: "fabulously-optimized", name: "fabulously-optimized") (downloads and installs in one step, all through HMCL) → launch_game(version: "fabulously-optimized", username: "Steve") — note: launch_game's version is the instance name from install_modpack/list_modpacks, not the Minecraft version number

2. Vanilla: install a version → launch

   install_version(mc_version: "1.21.4") → launch_game(version: "1.21.4", username: "Steve")

3. First run / fresh setup

   check_environment (verify java + hmcl dir) → install_hmcl (downloads HMCL.jar, builds the agent jar) → start_hmcl (boots the headless JVM, agent responds on /status)

4. Cleanup

   stop_game (stop the running game) → stop_hmcl (stop the headless JVM)

Troubleshooting

• javac not found / java missing: installing a JDK is the user's responsibility — install JDK 17+ (21 recommended) and make sure both java and javac are on PATH (or set HMCL_MCP_JAVA).

• First run downloads: install_hmcl downloads HMCL.jar (~10 MB) from GitHub releases and npm run build:agent downloads javafx-base/javafx-graphics from Maven Central — both need internet and can take a minute.

• install_hmcl fails with HTTP 403/429: GitHub API rate limit — download HMCL-<version>.jar manually and place it at <hmclDir>/HMCL.jar (see docs/setup.md), then re-run.

• CurseForge errors (403): missing/invalid API key — CurseForge is optional; use Modrinth (keyless) for search/install.

• Headless means no launcher window: only the game window appears, on launch_game.

• Port conflict: change HMCL_MCP_AGENT_PORT and restart; the agent binds 127.0.0.1 only.

• Paths containing !: HMCL refuses to run when the working directory or jar path contains ! — use a path without it.

Docs

• docs/setup.md — manual HMCL install, workdir layout, reusing an existing game directory, security notes

• docs/research/ — research notes (MCP SDK, HMCL Java API, HMCL CLI/modpack formats, Modrinth/CurseForge APIs)

• src/types.ts — the shared contract (tools, types, cross-module interfaces)