minecraft-mcp

A local MCP server that lets AI harnesses (Claude Code, Codex, Hermes, ...) perform every action a Minecraft player can — move, jump, break/place blocks, fight, manage inventory, chat — plus op-level extras (teleport, gamemode, weather/time, summon entities, console commands).

Architecture

AI Harness (Claude Code / Codex / Hermes)
   │  stdio (MCP protocol)
   ▼
src/  Node + TypeScript MCP server  (this repo, `npm run dev` / dist/index.js)
   │  WebSocket, JSON frames (see docs/bridge-protocol.md)
   ▼  ws://127.0.0.1:8765
plugin/  Java Paper plugin `minecraft-mcp-bridge`
   │  Bukkit/Paper API
   ▼
Local PaperMC server (server/ dir) — you join as the controlled player

The harness controls whoever is online on the server (you). Every tool accepts an optional player argument to target a specific online player.

Related MCP server: MCP Minecraft Remote

Prerequisites

• Node.js ≥ 18

• JDK ≥ 21 to build the plugin (JDK 24 works; the plugin is compiled for Java 21 bytecode)

• A Minecraft Java Edition client matching the server version

Quick start

npm install                          # install MCP server deps
node scripts/setup-server.mjs 26.2   # download Paper 26.2 into server/, accept EULA
npm run start:server                 # build plugin, install it, launch the server

Notes:

• setup-server.mjs takes an optional version argument (26.2, 1.21.11, ...). Without one it downloads the latest 1.21.x.

• Paper 26.1+ requires Java 25 to run (not just build). If a portable JDK is extracted under .jdk/ (e.g. .jdk/jdk-25.0.4+7/), start-server.mjs uses it automatically instead of the system java.

• Join localhost with a client matching the server version. The server runs with online-mode=false for local dev.

To verify everything end-to-end (requires the server running and a player online):

npm run smoke:bridge        # exercises every tool against the live server

Harness configuration

The MCP server runs over stdio. Build first (npm run build), then register:

Claude Code (claude mcp add):

claude mcp add minecraft -- node /path/to/minecraft-mcp/dist/index.js

Codex / other harnesses — equivalent stdio entry:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/minecraft-mcp/dist/index.js"]
    }
  }
}

Environment variable MINECRAFT_MCP_BRIDGE_URL overrides the bridge address (default ws://127.0.0.1:8765).

Tools

All tools take an optional player (defaults to the first online player).

The full tool/command contract is documented in docs/bridge-protocol.md.

Development

npm run typecheck     # TS typecheck
npm run build         # compile MCP server to dist/
npm test              # bridge unit tests (mock socket, no Minecraft needed)
npm run build:plugin  # build the Paper plugin jar (Gradle shadowJar)

Plugin jar output: plugin/build/libs/minecraft-mcp-bridge-0.1.0.jar. Bridge port is configurable in plugin/src/main/resources/config.yml (runtime copy: server/plugins/minecraft-mcp-bridge/config.yml).

Known limitations (v0.1)

• move_to is velocity-based steering, not pathfinding; it hops over 1-block obstacles but won't route around walls.

• Survival break_block uses a fixed 1s delay regardless of tool/hardness.

• use_item / interact_entity fire the Bukkit events but don't reproduce vanilla effects (eating, trading, mounting).

• Controls an online player; fake-player NPCs are future work.

Player-less operation

World-level commands (place_block, break_block, get_block_at, get_heightmap, run_command, set_time, set_weather, summon_entity with explicit coordinates) work with no player online, against the default world — so agents can build 24/7. Use run_command with forceload add to keep build regions' chunks loaded.

Showcase build scripts

The scripts/ directory contains the builds that grew the world, all driven through the bridge and verified with get_block_at sampling:

• build-house.ts — the original medieval house smoke test

• build-castle.ts / build-lighthouse.ts / build-bridge.ts — the three terrain-fitted marvels (SE hill keep, W shore lighthouse, channel arch bridge)

• build-aqueduct.ts / build-forum.ts / build-colossus.ts / build-span.ts / build-skyfall.ts / build-roads.ts — the Aurelian Reach megastructure program (run in that order)

• survey-terrain.ts / fine-survey.ts — ASCII relief maps from get_heightmap, used to pick sites from real terrain data

• lib-build.ts — shared Builder: plan queue with last-wins dedupe, carve-after-place, chunked console fills (vanilla 32768 limit), forceload helpers, tolerant placement, verification

License

MIT