Install, launch and control Minecraft: Java Edition clients and servers, also headless.
io.github.headlesshq/headlessmc-mcp MCP Server
The io.github.headlesshq/headlessmc-mcp Model Context Protocol (MCP) server is designed to install, launch, and control Minecraft: Java Edition clients and servers, including headless operation.
🛠️ Key Features
Install Minecraft: Java Edition clients and servers
Launch Minecraft: Java Edition clients and servers
Control Minecraft: Java Edition clients and servers
Supports headless use
🚀 Use Cases
Automating setup and startup of Minecraft: Java Edition servers
Running and managing clients or servers in headless environments
Programmatic control of Minecraft: Java Edition processes
⚡ Developer Benefits
Provides MCP access for installation, launch, and control workflows
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.
For instructions on HeadlessMc itself (installing it, mod testing in CI with MC-Runtime-Test), install the
headlessmc-skill as well.
Tools
Tool
Description
hmc
Run any HeadlessMc command line, e.g. version install fabric 1.21.5, mod search sodium, login. Long commands keep running, poll them with hmc_job.
hmc_job
Output and status of a running hmc command.
launch_client
Install and launch a client (version, loader or profile, headless, offline, server to join, JVM args) and wait until it shows the main menu.
start_server
Create and start a Paper/Fabric/Purpur/Forge/NeoForge/vanilla server and wait until it has loaded the world.
list_profiles, create_profile, delete_profile
Manage profiles: client setups with their own game directory.
list_instances
All launched clients and servers with their status.
instance_log
The latest lines of an instance's output, optionally filtered by a regex.
server_command
Write a console command to a server and return what it prints.
stop_instance
Quit a client or stop a server (or kill it).
get_screen
The current screen as JSON: buttons and text fields with ids, texts, positions.
get_state
JSON: in world, dead, screen, and metrics like position, health, dimension, server, ping, TPS, players.
click, set_text, press_key
Interact with the current screen. click returns the screen it leads to.
chat
Send a chat message or a /command.
connect, disconnect
Join or leave a server.
wait_for
Wait for in_world, menu, screen:<Name>, log:<regex> or exit.
game_command
Run any HMC-Specifics command inside the game (help, metrics, render, respawn, commands of other mods).
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.
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
Property
Default
Description
hmc.mcp.specifics.version
3.0.1
HMC-Specifics release to install into clients.
hmc.mcp.specifics.url
GitHub releases
Download URL template with {tag}, {mc} and {loader}.
hmc.files.game-for-each-version
true
Separate game directory per version, so mods folders do not clash.
hmc.mcp.registry
<state dir>/headlessmc-mcp/instances
Where games from other launchers register, set it for the game as well.
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.