HeadlessMc

HeadlessMc - MCP

An MCP server for HeadlessMc: install, launch and control Minecraft: Java Edition from AI agents.

HMC | HMC-Specifics | HMC-Skill

[!WARNING] This is a prototype. We are looking forward to feedback and feature requests.

With this MCP server, Claude Code, Codex, Cursor and other MCP clients can:

• install vanilla, Fabric, Forge and NeoForge versions, Java, and mods from Modrinth (everything HeadlessMc can do),
• launch several clients and servers at the same time, optionally headless (no display or GPU, e.g. in CI or Docker), each client in its own profile (game directory with its own mods, config and worlds),
• control running clients: read the screen, click buttons, type, chat, run commands, connect to servers, etc.
• read the logs of every instance and send console commands to servers.

Setup

For instructions on HeadlessMc itself (installing it, mod testing in CI with MC-Runtime-Test), install the headlessmc-skill as well.

Tools

Resource template: hmc://instances/{id}/log.

Several clients at once

Every running client needs its own game directory, otherwise they overwrite each other's files and share a mods folder. launch_client takes an optional profile: a HeadlessMc profile with its own game directory, created in <HeadlessMc data dir>/client/<profile> if it does not exist. Without a profile, a client uses the default game directory of its version, and if another client of that version is already running there, the MCP server creates a new profile (fabric-1.21.8-2, ...) automatically. Versions, libraries and assets are shared between all profiles. Agents can keep profiles for different setups and add mods to them with mod add mod <slug> <profile>.

Game Control

Game control works on every Minecraft version and modloader that HMC-Specifics supports (1.7.10 to 26.x, Forge, Fabric, NeoForge). The server downloads the matching HMC-Specifics jar and puts it, together with the version independent hmc-mcp-bridge mod, into the mods folder of the client before launching it.

• The root project (src/) is the MCP server, a Quarkus application. It uses HeadlessMc's CDI beans and picocli commands directly, like headlessmc-web. stdout is the MCP channel, so HeadlessMc's console output and progress bars are captured and returned as tool results instead.
• hmc-mcp-bridge is a mod that is not tied to a Minecraft version. It uses the HMC-Specifics API and starts a small HTTP server on the loopback interface once HMC-Specifics has initialized. The MCP server passes it a random token and a port file with -Dhmc.mcp.token and -Dhmc.mcp.portFile. Without a token the mod does nothing. Command output comes back separately from the game log, and JSON commands make the screen and state machine-readable.

Agents can also control clients you start yourself, with any launcher (the Minecraft Launcher, Prism, MultiMC, your IDE's run configuration, ...). Put two mods into the mods folder:

• HMC-Specifics for your Minecraft version and modloader,
• hmc-mcp-bridge from the releases, one jar for every version and modloader.

When a game with these mods was not launched by the MCP server, the bridge creates a random token, listens on a free port of 127.0.0.1 and registers the game in headlessmc-mcp/instances/<pid>.json in the user's state directory ($XDG_STATE_HOME, else ~/.local/state on Linux, ~/Library/Application Support on macOS, %LOCALAPPDATA%\state on Windows). The file is only readable by you and is deleted when the game exits. list_instances picks up these registrations, so the game appears as an attached instance, and the game tools work as for launched clients. The log comes from logs/latest.log. The MCP server never stops attached games on its own, and they have no console for server_command. Launch the game with -Dhmc.mcp.enabled=false to turn the bridge off.

Asking the user

Some things need the user, not the agent. The MCP server uses elicitation when the MCP client supports it:

• Minecraft EULA: start_server asks the user to accept the EULA with a checkbox before a server is started for the first time. Without elicitation support, the agent has to ask and pass acceptEula.
• Microsoft login: the login command asks the client to open Microsoft's device code page (URL mode), so the user signs in in their browser and the agent never sees credentials.
• Prompts of HeadlessMc commands are shown to the user as a form. Passwords and tokens are never requested, the MCP specification forbids that for form elicitation.
• Deleting a profile with its files asks for confirmation.

Long installs and launches send progress notifications, and cancelling a tool call in the client cancels the HeadlessMc command.

Installing

Download the latest release from GitHub Releases:

Building

Requires JDK 25:

git clone --recurse-submodules https://github.com/headlesshq/headlessmc-mcp.git
cd headlessmc-mcp
./gradlew build
# -> build/headlessmc-mcp-<version>-runner.jar (includes the hmc-mcp-bridge mod)
# -> hmc-mcp-bridge/build/libs/hmc-mcp-bridge-<version>.jar

# native executable for the current platform, needs GraalVM 25 (or add -Dquarkus.native.container-build=true for Linux)
./scripts/build-native.sh
# -> build/headlessmc-mcp-<version>-runner

Configuration

All HeadlessMc properties (hmc.*) work as well, as system properties or in HeadlessMc's config file.

The hmc-mcp-bridge mod reads hmc.mcp.token, hmc.mcp.portFile, hmc.mcp.host (127.0.0.1), hmc.mcp.port (0, any free port), hmc.mcp.registry and hmc.mcp.enabled (true) from system properties. Without hmc.mcp.token it registers the game for attaching.

Privacy and terms

The MCP server runs locally and sends no telemetry. See the Privacy Policy and the Terms of Use. HeadlessMc - MCP is not an official Minecraft product and is not approved by or associated with Mojang or Microsoft.