# HeadlessMc

An MCP server lets AI agents install and run Minecraft: Java Edition, control clients and servers, and inspect screens and logs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 8
- Author: headlesshq
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/headlesshq/headlessmc-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/headlessmc

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add headlessmc-mcp -- npx -y @headlesshq/headlessmc-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add headlessmc -- npx -y @headlesshq/headlessmc-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "headlessmc": {
            "command": "npx",
            "args": [
                "-y",
                "@headlesshq/headlessmc-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "headlessmc": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@headlesshq/headlessmc-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add headlessmc npx -y @headlesshq/headlessmc-mcp
```

## When to use it
- 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
- 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.

## Similar
- [minecraft-modding](https://affpapa.org/en/nevibecode/skills/minecraft-modding.md) — skill · 737 installs
- [fabricator-panel-mcp](https://affpapa.org/en/nevibecode/mcp/fabricator-panel-mcp.md) — MCP server · ★ 57
- [GodotLens](https://affpapa.org/en/nevibecode/mcp/godotlens.md) — MCP server · ★ 10
- [godot-gdscript-headless-testing](https://affpapa.org/en/nevibecode/skills/godot-gdscript-headless-testing.md) — skill · 3400 installs
- [blockbench-modeling](https://affpapa.org/en/nevibecode/skills/blockbench-modeling.md) — skill · 1300 installs
- [blockbench-animation](https://affpapa.org/en/nevibecode/skills/blockbench-animation.md) — skill · 1100 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md