# HeadlessMc

> HeadlessMc is an open-source MCP server for games and play. Install, launch and remote-control Minecraft Java clients and servers, headless or not. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Windows, macOS, Linux
- **Repository:** https://github.com/headlesshq/headlessmc-mcp
- **MCP Registry name:** io.github.headlesshq/headlessmc-mcp
- **Categories:** games and play, developer tools
- **Listing updated:** 2026-11-16

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "headlessmc-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "headlessmc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@headlesshq/headlessmc-mcp"
      ]
    }
  }
}
```

## Tools

- `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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/headlessmc
