
HeadlessMc
Install, launch and remote-control Minecraft Java clients and servers, headless or not
- Pricing
- Open source
- Platforms
- CLI, Windows, macOS
- Runs
- Locally
- Version
- 0.1.0
- Listing updated
- 1 day ago
About HeadlessMc
HeadlessMc is an open-source MCP server for games and play. It runs locally on your machine and is started by your AI client.
A prototype that hands an AI agent the controls of Minecraft: Java Edition through HeadlessMc. It can install vanilla, Fabric, Forge and NeoForge versions, Java itself and Modrinth mods, then launch several clients and servers at once, each client in its own profile with a separate game directory, mods and worlds. Clients can run headless with no display or GPU, which suits CI and Docker.
Once a game is running the agent can read the screen as JSON of buttons and text fields, click, type, press keys, chat, run commands, join servers and read state such as health, dimension, ping and TPS. A small bridge mod, working with HMC-Specifics across Minecraft 1.7.10 to 26.x, serves this on a loopback port protected by a random token. Games started from other launchers can be attached by adding two mods.
The user stays in the loop where it matters: the server asks via elicitation to accept the Minecraft EULA, Microsoft sign-in opens a device-code page so the agent never sees credentials, and deleting a profile with files asks for confirmation. Install through plugin marketplaces for Claude Code, Codex, Copilot CLI, Cursor or Gemini CLI, or run the jar with Java 25 or newer.
Install
Run in a terminal
claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"headlessmc-mcp": {
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"headlessmc-mcp": {
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"headlessmc-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"headlessmc-mcp": {
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"headlessmc-mcp": {
"command": "npx",
"args": [
"-y",
"@headlesshq/headlessmc-mcp"
]
}
}
}Tools this server provides (21)
Taken from the project documentation; the running server may differ.
- hmc
- Run any HeadlessMc command line
- hmc_job
- Output and status of a running hmc command
- launch_client
- Install and launch a client and wait for the main menu
- start_server
- Create and start a server and wait until the world loads
- list_profiles
- List client profiles
- create_profile
- Create a client profile
- delete_profile
- Delete a client profile
- list_instances
- List launched clients and servers with status
- instance_log
- Latest lines of an instance's output
- server_command
- Send a console command to a server
- stop_instance
- Quit a client or stop a server
- get_screen
- Current screen as JSON
- get_state
- Game state and metrics as JSON
- click
- Click a button on the current screen
- set_text
- Type into a text field
- press_key
- Press a key
- chat
- Send a chat message or command
- connect
- Join a server
- disconnect
- Leave a server
- wait_for
- Wait for a game state or log line
- game_command
- Run an HMC-Specifics command in game
What it does
- Version and mod install
- Installs vanilla and modded versions, Java and Modrinth mods.
- Parallel instances
- Runs several clients and servers, each with its own profile.
- Headless mode
- Runs without a display or GPU for CI and Docker.
- Screen control
- Reads the screen as JSON and clicks, types and chats.
- Server management
- Starts Paper, Fabric, Purpur, Forge, NeoForge or vanilla servers.
- User approval steps
- Asks the user for EULA, Microsoft login and profile deletion.
Good for
- Test a mod across several Minecraft versions in CI
- Let an agent start a server and run console commands
- Automate in-game checks by reading screen and state
- Keep separate mod profiles for different setups
Pricing
Open source
Free, open source
HeadlessMc FAQ
Is it production ready?
No. The README labels it a prototype.
Can an agent see my Microsoft credentials?
No. Login opens a device-code page in your browser.
What Java is needed?
Java 25 or newer for the jar release.
Can it control games started elsewhere?
Yes, if HMC-Specifics and the bridge mod are in the mods folder.
Is HeadlessMc free?
Yes. HeadlessMc is open source, so you can use and self-host it for free.
How do I add HeadlessMc to Claude Code?
Run this command in your terminal: claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcp
What are the best alternatives to HeadlessMc?
The closest alternatives to HeadlessMc are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to HeadlessMc

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools