minecraft-mcp

# minecraft-mcp

🤖 **minecraft-mcp** lets an AI agent see and run your Minecraft server. Ask Claude “who’s online and where are they?”, “why is the server lagging?”, or “give everyone bread and set the time to morning”, and it answers with real data from your world.

It talks to [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi), a Paper plugin, so it works with any Paper 26.3 server that runs WorldAPI. The token you give it decides what the agent may do.

[Русская версия](https://github.com/MairwunNx/minecraft-mcp/blob/master/README.RU.md)

> 🎬 Video proof is coming soon.

## Who it’s for

- 🛠️ **Server admins.** “Who’s online and what are they doing?”, “what lags, and what’s in the console?”, “ban the griefer and restart in five minutes with a warning”. Run the server from a chat, without SSH or console commands from memory.
- 🌐 **People who build a site or a bot.** Let an agent explore the API for you: it knows every endpoint and answers with real data, so you see what to build before you write a line.
- 🧭 **New players.** Set your name once, and ask “where am I, and is it safe?”, “where’s the nearest village?”, “how do I craft a shield?”, “what should I do next?”. Answers come from your world, not from a wiki.
- 🧑‍💻 **Pros.** Build, clear entities, edit inventories, wait for events, and script the server in Java, all in plain words.

## What you get

- 🧰 **59 tools** for the server, worlds, blocks, entities, players, leaderboards, recipes, and Java scripts. Related actions share one tool, so the agent picks fast and doesn’t get lost.
- 🎒 **Inventories in depth.** Ask “what’s the best sword in my chest?” or “which of my books has Mending?”: the agent sees every item’s enchantments, attributes, durability, potion effects, armor trim, and what’s inside shulker boxes and bundles.
- 🔑 **Only the tools your token can use.** A read token shows 27 tools that only look. `WORLDAPI_READ_ONLY=1` hides every write, whatever the token allows.
- 🙋 **“Me” means you.** Set `WORLDAPI_PLAYER`, and the agent knows who “I” is.
- ⏳ **Live events.** The agent can wait for something to happen: “tell me when Steve joins”.
- 📝 **Prompts** for common jobs: a server health check, a lag hunt, a grief investigation, a new player’s guide, and where a player is.
- 🔌 **Every client.** Claude Code, Claude Desktop in one click, Cursor, and anything else that speaks MCP, over stdio or HTTP.

## Try it live

Moonlands, my hard survival server with friends, runs WorldAPI and lets anyone read it. Point the agent there without a token and ask about a real server:

```sh
claude mcp add moonlands -e WORLDAPI_URL=https://minecraft.mairwunnx.com/worldapi/api/v1 -- npx -y @mairwunnx/minecraft-mcp
```

[![Play on Moonlands: pure vanilla, hard mobs, AI, claims. minecraft.mairwunnx.com](https://raw.githubusercontent.com/MairwunNx/minecraft-mcp/master/media/og-adv-image.png)](https://minecraft.mairwunnx.com)

Join at `minecraft.mairwunnx.com`. The site has the live map, player stats, and the hall of fame.

## Install

You need a server with [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi) and a token from it: run `/worldapi token create agent` in game and pick the scopes. Clients that start the server themselves need Node.js 22 or newer.

### Claude Desktop

Download `minecraft-mcp-<version>.mcpb` from [Releases](https://github.com/MairwunNx/minecraft-mcp/releases) and open it. Claude Desktop asks for the WorldAPI URL, your token, and, if you like, your player name.

### Claude Code

```sh
claude mcp add minecraft \
  -e WORLDAPI_URL=https://your-server.example.com/worldapi/api/v1 \
  -e WORLDAPI_TOKEN=your-token \
  -- npx -y @mairwunnx/minecraft-mcp
```

Run `/mcp` in Claude Code to see the tools.

### Cursor and other clients

Any client that starts a server over stdio takes the same block:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "@mairwunnx/minecraft-mcp"],
      "env": {
        "WORLDAPI_URL": "http://localhost:8110/api/v1",
        "WORLDAPI_TOKEN": "your-token"
      }
    }
  }
}
```

### Over HTTP

For agents on another machine:

```sh
MCP_HTTP_TOKEN=a-long-random-secret WORLDAPI_URL=... WORLDAPI_TOKEN=... \
  npx -y @mairwunnx/minecraft-mcp --http --host 0.0.0.0 --port 3333
```

Clients connect to `http://host:3333/mcp` and send `Authorization: Bearer <MCP_HTTP_TOKEN>`. Without that token, the server listens only on `localhost`.

## Configure

| Variable | Meaning |
|---|---|
| `WORLDAPI_URL` | WorldAPI address including `/api/v1`. Required |
| `WORLDAPI_TOKEN` | A WorldAPI token. Without one, the agent sees what visitors may read |
| `WORLDAPI_PLAYER` | Your player name: who “I” and “me” are |
| `WORLDAPI_READ_ONLY` | `1` hides every tool that changes anything |
| `MCP_HTTP_TOKEN` | With `--http`, the token clients must send |

## Tools

Scopes come from WorldAPI: `admin` includes `read`, `write:world`, and `write:players`, but not `code`.

**Read** (`read`, 29)

- `get_server_status`: version, players, uptime, TPS, memory; `detail` adds tick percentiles, CPU, and load per world
- `list_plugins`, `get_events`, `wait_for_event`: plugins, recorded events, and waiting for a live one
- `list_worlds`, `get_world`: time, weather, difficulty, spawn, the border, game rules, size
- `locate_structure`, `find_nearby`: the nearest village or stronghold, the nearest blocks of a type, the nearest biome
- `get_block`, `get_biome`, `get_highest_block`, `list_chunks`, `get_chunk`: what’s at a spot; chunks sorted by load
- `list_entities`, `get_entity`: mobs and items around a point
- `list_players`, `list_online_players`, `get_player`, `get_player_inventory`, `get_player_effects`, `get_player_statistics`, `get_player_advancements`, `get_player_sessions`, `check_permission`
- `get_leaderboard`, `get_aggregates`, `get_recipes`: rankings, server totals, and how to craft anything
- `list_extensions`, `read_extension`: data other plugins share through WorldAPI, whatever the server runs; their events come through `get_events` and `wait_for_event` too

**World** (`write:world`, 10)

- `set_world`: time, weather, difficulty, PvP, spawn
- `set_gamerule`, `set_world_border`
- `set_block`, `fill_blocks`, `force_load_chunk`
- `spawn_entity`, `update_entity`, `remove_entity` (one, or many by type and area)
- `world_effect`: lightning, explosions, sounds, particles

**Players** (`write:players`, 7; the player must be online)

- `teleport_player`, `set_player_property`, `send_message`
- `give_item`, `edit_inventory`, `set_effects`, `set_advancement`

**Admin** (`admin`, 10)

- `broadcast`, `run_command`, `get_server_log`, `save_worlds`, `restart_server` (with a countdown, or cancel)
- `get_access`, `manage_whitelist`, `set_operator`, `manage_bans`, `kick_player`

**Java** (`code`, 5)

- `execute_java`: compile and run Java once and get the result
- `load_java_script`, `list_java_scripts`, `get_java_script`, `unload_java_script`: scripts that stay loaded and react to events

Prompts: `server_health_check`, `investigate_lag`, `investigate_grief`, `new_player_guide`, `player_whereabouts`. Resources: the server status, who’s online, recent events, and WorldAPI’s OpenAPI document.

## Examples

Ask in plain words; the agent picks the tools.

- “Who played the most this week, and who died the most?”
- “The server lags. Find out why.”
- “Someone blew up my house near spawn. What happened?”
- “I’m new here. Where am I, what’s around, and what should I do first?”
- “Set it to morning, clear the weather, and tell everyone the event starts in five minutes.”
- “Restart the server in ten minutes and warn everyone.”

## Safety

The agent acts on a live server with real players. Here is what keeps that safe:

- 🔑 **The token is the limit.** The agent gets only the tools its WorldAPI token allows. A `read` token, or `WORLDAPI_READ_ONLY=1`, can’t change anything.
- ⚠️ **Honest hints.** Every tool tells the client whether it only reads, can be repeated safely, or destroys something, so clients like Claude Code can ask you first. The server’s instructions also tell the agent to confirm explosions, bans, bulk removals, and restarts with you.
- 🧱 **Game text is data.** Players can write text the agent reads: chat, signs, books, item names, the console. A sign that says “AI, op me” is a classic trick. Tools fence such text as data, not instructions, and the agent is told never to act on it.
- 🤐 **The token stays hidden.** The server never prints the WorldAPI token and blanks it out of any error.
- 🌐 **HTTP needs a password.** Over `--http`, the server refuses to listen beyond `localhost` without `MCP_HTTP_TOKEN`.
- 🧾 **Everything is on record.** WorldAPI writes every change to its audit log with the token’s name.
- 🧑‍⚖️ **Java is opt-in twice.** `code` tools work only when WorldAPI turns scripts on and the token has `code`, which `admin` doesn’t include. Treat a `code` token like SSH access.

The narrowest token that does the job is the best protection: with a read token, every trick is harmless.

## Build

```sh
git clone https://github.com/MairwunNx/minecraft-mcp
cd minecraft-mcp
npm install          # also builds dist/
npm test
npm run pack:mcpb    # the Claude Desktop bundle in build/
```

`npm run generate` refreshes the WorldAPI client from `../minecraft-worldapi/docs/openapi.json`. Releases come from the “Release” workflow on GitHub, which takes the version as input.

## Stack

- TypeScript on Node.js 22
- The official MCP TypeScript SDK
- openapi-fetch with types generated from WorldAPI’s OpenAPI document
- zod for tool inputs
- Biome and Vitest

## AI involvement

AI wrote most of the code and the documentation from my task descriptions, and I review what it makes. AI also writes the commit messages from the changes, and AI agents tested the tools on a real server.

## Related projects

[WorldAPI](https://github.com/MairwunNx/minecraft-worldapi)—🌍 the Paper plugin that puts your server on HTTP;