# Minecraft Client MCP

A local [Model Context Protocol](https://modelcontextprotocol.io/) server that gives an agent end-to-end control of a Minecraft Java Edition client through [Mineflayer](https://github.com/PrismarineJS/mineflayer).

It supports offline/no-auth and Microsoft device-code login, chat and slash commands, pathfinding and direct controls, combat, block/entity interaction, inventory and container UIs, event-driven chat/state reads, compact world snapshots, nearby block/entity queries, and an opt-in raw packet escape hatch.

Server resource-pack requests are acknowledged automatically with `ACCEPTED` followed by `SUCCESSFULLY_LOADED`, including requests received during configuration or before the bot spawns. The MCP normalizes Mineflayer's UUID reply to the protocol's string representation, preventing configuration stalls on strict servers such as Minestom. Mineflayer handles configuration-phase packets; the MCP listener handles login/play-phase requests without sending duplicates. The bot reports success to the server but does not download or render the pack.

## Session dashboard

The MCP process starts a read-only dashboard at `http://127.0.0.1:3210`. It shows:

- Prior and current Minecraft connection sessions, including server, player, version, timestamps, and outcome.
- MCP actions and Minecraft events as they happen over a live server-sent event stream.
- Action inputs, results, failures, and execution duration.
- PNG world captures associated with the session in which they were taken.

History is retained across MCP restarts in `~/.minecraft-client-mcp/activity.jsonl`; captures are stored under `~/.minecraft-client-mcp/captures`. Multiple MCP processes share and periodically reconcile this journal, so their current sessions appear together. Call `minecraft_dashboard` to open the page in the default browser, or set `MINECRAFT_DASHBOARD_OPEN=true` to open it whenever the MCP process starts.

The dashboard deliberately binds to localhost and has no write endpoints. Action history can contain chat messages, commands, usernames, and server addresses, so protect the dashboard data directory like any other local application history.

## Minecraft version compatibility

- **26.1:** supported and included in Mineflayer's tested-version list.
- **26.1.1 / 26.1.2:** supported through the shared 26.1 protocol and game-data mapping.
- **26.2:** not yet safe to claim as supported. Its protocol number is registered, but the currently published Mineflayer stack does not include complete 26.2 game data or list it as a supported client version. The upstream 26.2 Mineflayer and protocol changes are still under review.

Use `minecraft_versions` or read `minecraft://versions` to inspect compatibility at runtime. The server validates an explicitly requested version before connecting, and omitting `version` still enables normal server auto-detection. A 26.2 server can only be used today if it provides a compatible 26.1 endpoint, such as a correctly configured ViaVersion/ViaBackwards setup.

## Requirements

- Node.js 22 or newer
- A reachable Minecraft Java Edition server
- For Microsoft auth, an account entitled to Minecraft Java Edition

## Install and build

```bash
npm install
npm run build
```

Run it directly over stdio:

```bash
npm start
```

For development:

```bash
npm run dev
```

## MCP client configuration

### Claude Code: install directly from GitHub

After this repository is published, Claude Code can install and launch it without a manual clone:

```powershell
claude mcp add minecraft --scope user -- cmd /c npx -y github:CDX-1/minecraft-client-mcp
```

Verify the connection with:

```powershell
claude mcp get minecraft
```

On macOS or Linux, omit the Windows `cmd /c` wrapper:

```bash
claude mcp add minecraft --scope user -- npx -y github:CDX-1/minecraft-client-mcp
```

### Local checkout

Use an absolute path in real MCP client configuration. For example:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["D:/projects/minecraft-client-mcp/dist/index.js"],
      "env": {
        "MINECRAFT_AUTH_CACHE": "D:/projects/minecraft-client-mcp/.minecraft-auth"
      }
    }
  }
}
```

The server writes protocol data only to stdout; diagnostics and Microsoft device-code instructions go to stderr.

## Login flows

Call `minecraft_connect` with:

- `auth: "offline"` for offline-mode/no-auth servers. `username` is the in-game name.
- `auth: "microsoft"` for online-mode servers. The first login returns or emits a `msa_code` event containing the verification URL and user code. Complete that browser flow, then poll `minecraft_status` or wait on `minecraft_events`. Tokens are cached by default in `.minecraft-auth` (configurable below).

Only one Minecraft session is managed by each MCP server process. Call `minecraft_disconnect` before connecting to a different server.

## Tools

| Tool | Purpose |
|---|---|
| `minecraft_connect` / `minecraft_disconnect` | Session lifecycle and offline/Microsoft authentication |
| `minecraft_status` | Connection, health, food, position, dimension, held item, and auth state |
| `minecraft_versions` | Installed Mineflayer compatibility and modern-version probes |
| `minecraft_events` | Cursor-based read/long-poll for chat, messages, combat, players, windows, and connection events |
| `minecraft_chat` | Chat, whisper, and slash-command execution |
| `minecraft_move` | A* pathfinding, dynamic following, low-level controls, and stop |
| `minecraft_look` | Aim at a point/entity or set yaw and pitch |
| `minecraft_attack` | Select, approach, aim at, and attack entities |
| `minecraft_inventory` | Inspect, equip, toss, select hotbar, click/move slots, transfer container stacks, and close windows |
| `minecraft_open` | Open container blocks or activate entity UIs |
| `minecraft_block` | Inspect, activate, dig, and place against blocks |
| `minecraft_entity` | Inspect, activate, use-on, mount, and dismount |
| `minecraft_use_item` | Activate, consume, deactivate, or swing |
| `minecraft_world_snapshot` | Palette-compressed nearby blocks, entities, and bot state |
| `minecraft_find_blocks` | Efficient nearest-block lookup by registry name |
| `minecraft_entities` | Bounded and filtered entity query |
| `minecraft_capture` | Save and return a top-down PNG world capture |
| `minecraft_dashboard` | Return or open the live local session dashboard |
| `minecraft_raw_packet` | Opt-in protocol-level packet write |

Four MCP resources are also available: `minecraft://status`, `minecraft://versions`, `minecraft://events/recent`, and `minecraft://dashboard`.

### Efficient world-state loop

For agent workflows, use this pattern:

1. Read `minecraft_status` once.
2. Use `minecraft_world_snapshot` with a small radius (the default is 8). Blocks are tuples indexed into a name palette, which avoids repeating block names.
3. Use `minecraft_find_blocks` for goal-directed searches instead of requesting a large cube.
4. Track the `latestSequence` returned by `minecraft_events`, and pass it back as `afterSequence` to read only deltas.

Structured snapshots remain the most token-efficient source for agent decisions. When visual context is useful, `minecraft_capture` creates a deterministic top-down PNG showing nearby terrain, entities, and the bot position; the result is returned to the agent and archived in the dashboard.

## Environment variables

| Variable | Default | Meaning |
|---|---:|---|
| `MINECRAFT_AUTH_CACHE` | `.minecraft-auth` | Microsoft token cache directory |
| `MINECRAFT_CONNECT_TIMEOUT_MS` | `60000` | Spawn timeout, from 1s to 5m |
| `MINECRAFT_EVENT_BUFFER_SIZE` | `500` | Retained event count |
| `MINECRAFT_MAX_SNAPSHOT_BLOCKS` | `5000` | Hard ceiling for blocks returned per snapshot |
| `MINECRAFT_MAX_SNAPSHOT_ENTITIES` | `256` | Hard ceiling for entities returned per snapshot |
| `MINECRAFT_ALLOW_RAW_PACKETS` | `false` | Enables `minecraft_raw_packet` when exactly `true` |
| `MINECRAFT_DASHBOARD_ENABLED` | `true` | Start the dashboard alongside the MCP server |
| `MINECRAFT_DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind address |
| `MINECRAFT_DASHBOARD_PORT` | `3210` | Preferred port; the next ten ports are tried if occupied |
| `MINECRAFT_DASHBOARD_OPEN` | `false` | Open the dashboard in the default browser at startup |
| `MINECRAFT_DASHBOARD_DATA_DIR` | `~/.minecraft-client-mcp` | Persistent journal and capture directory |

## Raw packet safety

Raw packets bypass Mineflayer's high-level state model. Packet names and payloads are Minecraft-version-specific; malformed writes may disconnect the client or desynchronize local state. The tool is disabled by default and should only be enabled for trusted MCP callers.

## Verification

```bash
npm run build
npm test
npm run test:stdio
```

The automated suite validates event cursors, persistent session history, PNG capture encoding, dashboard HTTP security and state endpoints, plus in-memory and stdio MCP handshakes. Connecting to a real server is intentionally left as an environment-specific integration check.

## Scope and security

This is a local stdio MCP server, so transport authentication is delegated to the host MCP application. Minecraft authentication is handled by Mineflayer/minecraft-protocol. Treat access to this MCP server as equivalent to control of the connected player: tools can run permitted server commands, move items, alter the world, attack entities, and—when explicitly enabled—send arbitrary packets.