Minecraft Client MCP

A local Model Context Protocol server that gives an agent end-to-end control of a Minecraft Java Edition client through 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.

Related MCP server: Maicraft

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

npm install
npm run build

Run it directly over stdio:

npm start

For development:

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:

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

Verify the connection with:

claude mcp get minecraft

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

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:

{
  "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

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

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

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.