# minecraft-mcp

A local [MCP](https://modelcontextprotocol.io) 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

```bash
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):

```bash
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`):

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

**Codex / other harnesses** — equivalent stdio entry:

```json
{
  "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](docs/bridge-protocol.md).

## Development

```bash
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