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.

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).

Category	Tool	What it does
Movement	look_at	Face a block/position
	move_to	Walk/sprint toward coordinates (timeout-aware)
	jump / sprint / sneak / stop	Movement state control
Interaction	break_block / place_block	Block manipulation
	use_item / attack / interact_entity	Right-click / combat
Inventory	get_inventory / equip_item / drop_item / swap_hands	Full inventory control
Info	get_player_state / get_block_at / get_nearby_entities / get_time_weather	World & player queries
Chat	send_chat	Chat as the player
Extras	teleport / set_gamemode / give_item / set_time / set_weather / summon_entity / run_command	Beyond player capabilities

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.

License

MIT