HeadlessMc — Claude Code MCP server: setup
An MCP server lets AI agents install and run Minecraft: Java Edition, control clients and servers, and inspect screens and logs.
claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcpWhat HeadlessMc does
HeadlessMc connects Minecraft: Java Edition to MCP clients. An agent can install vanilla, Fabric, Forge, or NeoForge versions, fetch mods from Modrinth, launch several clients and servers, join a server, send chat or console commands, and inspect instance logs.
Its tools cover profiles, running instances, screens, and game state. launch_client waits for the main menu, while start_server waits for the world to load. Other tools can click controls, enter text, wait for events, and run commands in the game or server. Headless operation removes the need for a display or GPU, which fits CI and Docker runs.
Game control relies on HMC-Specifics plus the hmc-mcp-bridge mod. Without separate profiles, clients of the same version can share a game directory, so parallel runs need their own profiles. Supported game control spans Minecraft 1.7.10 to 26.x with Forge, Fabric, and NeoForge.
What it helps with
- install a Minecraft version with a loader
- run parallel clients in separate profiles
- inspect and control a client screen
- read instance logs and issue server commands
- run a client without a display in CI
Example prompts for the agent
- Install Fabric 1.21.5 and launch the client without a display.
- Create a separate profile, start a Paper server, and wait for its world to load.
- Read the current client screen, then send a chat message.
How to install HeadlessMc
Platform CLI
claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcpPlatform CLI
codex mcp add headlessmc -- npx -y @headlesshq/headlessmc-mcpConfig file
{
"mcpServers": {
"headlessmc": {
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Config file
{
"servers": {
"headlessmc": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Platform CLI
gemini mcp add headlessmc npx -y @headlesshq/headlessmc-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about HeadlessMc
How do I install HeadlessMc in Claude Code?
Run claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcp.
What does HeadlessMc do?
It gives an AI agent tools to install and launch Minecraft: Java Edition, control clients and servers, and read screens and logs.
Which Minecraft versions and loaders support game control?
Game control covers versions 1.7.10 through 26.x with Forge, Fabric, and NeoForge through HMC-Specifics.
