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 (JDK 24 works; the plugin is compiled for Java 21 bytecode)

• A Minecraft Java Edition client (to join the local server)

Quick start

npm install                 # install MCP server deps
npm run setup:server        # download Paper 1.21.x into server/, accept EULA
npm run start:server        # build plugin, install it, launch the server

Then join localhost with your Minecraft client, and point your harness at the MCP server (see below). To verify everything end-to-end:

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.

License

MIT