Mine AI MCP

Batteries-included MCP runtime for letting AI play Minecraft. Mine AI MCP provides external AI agents with reliable, observable tools to inspect, navigate, and act in Minecraft. Every tool reports what was directly observed in the game world.

An agent running this server played a fresh world through to the Ender Dragon in a single unbroken session. The recording of that run is on YouTube, and its complete artifacts — the agent's transcript, the runtime's SQLite database, the server logs, and the seed prompt — are published as a dataset on Hugging Face.

Quick start: use an existing Minecraft server

Run it straight from the public repository with Bun. The package executes its TypeScript source, so there is no build step:

bunx github:aibengineering/mine-ai-mcp --minecraft-host 127.0.0.1 --minecraft-port 25565 --username MineAI --version 1.21.4

This starts a persistent MCP host at http://localhost:25575/mcp and joins the specified Minecraft Java server. Keep it running, then connect your AI client using the examples below. Pin a commit for reproducible runs, for example github:aibengineering/mine-ai-mcp#<commit>. The default --auth offline is for offline-mode servers; use --auth microsoft with a Minecraft account for a server that requires authenticated players.

You need Bun 1.4 or newer, a reachable Minecraft Java server (tested with 1.21.4), and Git for the current Git-pinned dependencies. Bun installs the JavaScript dependencies automatically. You do not need a separate Node runtime, Java installation, Docker, Claude Code, or Mine Labs to run just this MCP host; Java is needed wherever you host the Minecraft server itself. Use whichever MCP client you prefer to control the bot.

bunx downloads missing packages into Bun's shared cache without adding them to your project's dependencies. It still downloads and executes code; the cache is not an isolated sandbox. Persistent bot data goes to ~/.mine-ai/bot-data, separate from the cache; override it with --data-root.

From a source checkout, install dependencies and run the same entry point:

bun install
bun src/server/host.ts --minecraft-host 127.0.0.1 --minecraft-port 25565 --username MineAI --version 1.21.4

Complete documentation lives in docs/mcp/README.md.

Tool output schemas use compact local references by default. If a client has incompatible reference handling, add --inline-output-schemas to the host command to restore the previous SDK representation. Actual Claude/Codex host compatibility with this catalogue remains unverified; see the schema compatibility notes.

Run a local Claude playthrough with the Docker playthrough setup.

Rebuild the run that beat the game

The commit that defeated the Ender Dragon is tagged beat-the-game. Dockerfile.beatthegame clones that exact commit from this repository, pins its base images by digest, and reads nothing from your checkout, so anyone can rebuild the winning image from source. Use the same two Compose files for every step so the image you run is the one you built:

docker compose -f compose.yaml -f compose.beatthegame.yaml build
docker compose -f compose.yaml -f compose.beatthegame.yaml run --rm -e RUN_MODE=login play
EULA=true RUN_DIR=./runs/beat-the-game \
  docker compose -f compose.yaml -f compose.beatthegame.yaml up --abort-on-container-exit

The overlay pins the winning run's seed (97996358), bot name (AI_M1KE), model (claude-opus-5[1m]), and effort (high). Those reproduce the world and the setup, not the play itself, which is not deterministic. Set EULA=true only after accepting https://aka.ms/MinecraftEULA. The login is a one-time step. The image records the commit it was built from at /etc/mine-ai-mcp-commit. A plain docker compose build overwrites the same image tag with your checkout, so rebuild with both files before rerunning. See the Docker playthrough setup for the run directory layout, stopping, and resuming.

You do not have to rerun it to inspect it: that run's artifacts are published at aibengineering/beat-the-game-minecraft — 1,121 rows of agent transcript, the runtime's SQLite database with every tool call and its outcome, the vanilla server log carrying the Free the End advancement, and the prompt the agent was given. The recording is on YouTube.

Connect an MCP client

Start the Docker playthrough stack or the standalone host first. The endpoint is http://localhost:25575/mcp (Streamable HTTP); /health reports host status. These commands register a running server with your client; they do not install or start Minecraft. This package is not yet published to npm, so there is no npx or bunx package-install command to advertise yet.

Allow long Minecraft actions

Configure your harness's tool execution and idle timeouts, not just its connection/startup timeout. Smelting a stack in one ordinary furnace takes over ten minutes; collection and travel can also be long-running. In our Claude Code 2.1.268 run, a smelting call hit the HTTP client's five-minute idle timeout while the server continued working. A timed-out client request does not prove the Minecraft action stopped: inspect status before retrying; another action may return ACTION_BUSY.

We use 3600000 ms (one hour) per Minecraft call to give these actions headroom while retaining a finite client wait. Increase it for longer intended actions. Client settings are not interchangeable: check both idle and overall limits in any harness you use, and any proxy between it and the server.

Claude Code

Register the server with the timeout included (Bash/WSL or PowerShell):

claude mcp add-json --scope project minecraft '{"type":"http","url":"http://localhost:25575/mcp","timeout":3600000}'

In Windows Command Prompt, use escaped double quotes instead:

claude mcp add-json --scope project minecraft "{\"type\":\"http\",\"url\":\"http://localhost:25575/mcp\",\"timeout\":3600000}"

The resulting .mcp.json configuration is:

{
  "mcpServers": {
    "minecraft": {
      "type": "http",
      "url": "http://localhost:25575/mcp",
      "timeout": 3600000
    }
  }
}

Claude Code's per-server timeout controls execution time and, since v2.1.203, also sets the minimum idle window. MCP_TIMEOUT is only the startup timeout; raising MCP_TOOL_TIMEOUT alone does not remove the separate idle limit. See Claude MCP setup and timeout variables. Our container uses the same setting in docker/mcp.json. Rebuild the image before the next run to include config changes; editing the checkout does not change a running Claude process.

VS Code and Cursor

VS Code provides a registration command (Bash/WSL or PowerShell):

code --add-mcp '{"name":"minecraft","type":"http","url":"http://localhost:25575/mcp"}'

Run it for the VS Code installation/profile where your agent runs. You can also use MCP: Add Server in the Command Palette. See VS Code MCP setup.

For Cursor, add this to .cursor/mcp.json or your user ~/.cursor/mcp.json:

{
  "mcpServers": {
    "minecraft": { "url": "http://localhost:25575/mcp" }
  }
}

Cursor also supports one-click MCP install links. These VS Code/Cursor examples register the connection only; they do not establish a one-hour timeout. Verify your client's long-call behavior before a playthrough; do not assume Claude's timeout field works in another client's schema.

Documentation pages

• Overview: Quick start, host startup flags, and making a first call.
• Async actions: Submit work, inspect progress, retrieve typed results, before starting the next objective.
• Concepts: Quality standard, layered architecture, foreground locking, and lifecycle.
• Tools: Every published tool grouped by job, arguments, and verification evidence.
• Bot data: SQLite storage, tables and views, worked example queries, and query bounds.
• Events and responses: Response representations, notification summaries, and event stream cursors.
• Testing: Mine Labs scenario suites, playtests, and test execution scripts.
• Limitations: Current capability and dependency boundaries.

Further reading

• Bot data query guide: Read-only SQL surface, safety constraints, and query design.
• Navigation: Navigation APIs, movement, search, execution, and telemetry.
• Survival: Combat, environmental responses, and request continuation.

Note: upstream fixes

We pin our forks in package.json; overrides select the shared transitive dependencies. Keep these pins until equivalent fixes are available in upstream releases.

Repository	Fork revision	Diff from upstream master	Why we carry it
Mineflayer	9fa1140b90877a084efd988905df0c0eceaa78d0	Compare	Fixes item-use and air metadata ownership, stale respawn metadata, partial item pickups, crafting inventory synchronization, and placement acknowledgements. Includes regression tests and a trace-test parsing correction. The earlier player-loaded fix is now upstream. Preserves item use through hurt and shield-block statuses and tracks item use by active hand and item identity.
prismarine-physics	56a6794611069272653b14eb078a1454633f4eb3	Compare	Tolerates floating-point drift at block contacts, avoiding stalled movement and rejected jumps (PR #135). Uses the requested movement for the step-up probe, fixing carpet steps under low ceilings (PR #140).
prismarine-recipe	542f0600f5ddf07bb16df67fa1ac06e603bd28e0	Compare	Computes returned crafting containers from the output shape, fixing bucket and bottle inventory deltas.
node-minecraft-data (JavaScript wrapper)

The forks include upstream updates fetched on 11 September 2026. We install minecraft-data from a release archive containing the pinned game data and generated JavaScript; Bun's Git download did not include the data submodule.

Block highlighter and the Mine Labs development dependency are pinned to GitHub commits in package.json. They currently require engineering GitHub access; see the Docker instructions for temporary build authentication.