Skip to content
MCP server

HeadlessMc

Install, launch and remote-control Minecraft Java clients and servers, headless or not

Runs locallyStatus and history
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-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools