Minecraft Mcp

minecraft-mcp

MCP (Model Context Protocol) servers for AI-assisted Minecraft development. Lets tools like Claude Code interact directly with a running Minecraft server and client — viewing logs, running commands, installing plugins, taking screenshots, controlling the player, and calling arbitrary Bukkit/Paper/Minecraft API methods via reflection.

---

Repository layout

minecraft-mcp/
├── packages/
│   ├── shared/              TypeScript protocol types + WebSocket connection class
│   ├── mcp-server-paper/    MCP server (stdio) ↔ Paper/Spigot plugin
│   └── mcp-server-fabric/   MCP server (stdio) ↔ Fabric client mod
└── minecraft/
    ├── paper-plugin/        Paper/Spigot plugin (Java 21, Gradle)
    └── fabric-mod/          Fabric client mod for MC 26.1.2 (Java 25, Gradle 9.4, fabric-loom 1.16)

---

Architecture

┌──────────────────────┐        stdio         ┌────────────────────────────┐
│  Claude Code / LLM   │ ◄──────────────────► │  mcp-server-paper (Node)   │
└──────────────────────┘                       └──────────┬─────────────────┘
                                                          │  WebSocket
                                               ┌──────────▼─────────────────┐
                                               │  Paper plugin (Java)        │
                                               │  ws://localhost:25575       │
                                               └────────────────────────────┘

┌──────────────────────┐        stdio         ┌────────────────────────────┐
│  Claude Code / LLM   │ ◄──────────────────► │  mcp-server-fabric (Node)  │
└──────────────────────┘                       └──────────┬─────────────────┘
                                                          │  WebSocket
                                               ┌──────────▼─────────────────┐
                                               │  Fabric mod (Java)          │
                                               │  ws://localhost:25576       │
                                               └────────────────────────────┘

The Minecraft side (plugin / mod) runs a local WebSocket server. The Node.js MCP servers connect to it as clients. Claude Code (or any MCP host) runs the Node.js processes and talks to them over stdio.

---

Quick start

Prerequisites

| Tool | Version | |------|---------| | Node.js | ≥ 20 | | tsx | any (npm install -g tsx) | | Java | 21 (Paper plugin) / 25 (Fabric mod – MC 26.1.2 ships Java 25 bytecode) | | Gradle | 8.8+ for the Paper plugin wrapper. The Fabric mod has its own checked-in wrapper pinned to 9.4. |

1. Install Node packages

npm install

2. Build the Paper plugin

cd minecraft/paper-plugin
gradle wrapper --gradle-version 8.8   # once only
./gradlew shadowJar
# Output: build/libs/minecraft-mcp-paper-0.1.0.jar

Copy the jar into your Paper server's plugins/ directory and start the server.

3. Build the Fabric mod

cd minecraft/fabric-mod
./gradlew build       # uses the bundled wrapper (Gradle 9.4) – needs Java 25 on JAVA_HOME
# Output: build/libs/minecraft-mcp-fabric-0.1.0.jar

Copy the jar into your Fabric client's mods/ directory and launch Minecraft.

4. Configure Claude Code (.claude/mcp.json)

{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["--import", "tsx/esm", "/path/to/packages/mcp-server-paper/src/index.ts"],
      "env": {
        "PAPER_WS_URL": "ws://localhost:25575"
      }
    },
    "minecraft-fabric": {
      "command": "node",
      "args": ["--import", "tsx/esm", "/path/to/packages/mcp-server-fabric/src/index.ts"],
      "env": {
        "FABRIC_WS_URL": "ws://localhost:25576"
      }
    }
  }
}

---

Available tools

Paper / Spigot server (mcp-server-paper)

| Tool | Description | |------|-------------| | get_server_logs | Tail logs/latest.log, optional text filter | | subscribe_server_logs | Push future log lines to the MCP client | | run_console_command | Run a console command, capture output | | list_online_players | List online players | | list_plugins | List loaded plugins | | install_plugin | Copy a jar into plugins/, optional hot-load | | reload_plugin | Disable + re-enable a named plugin | | restart_server | Restart or stop the server | | reflect_invoke | Call any server-side method via reflection | | reflect_get_field | Read a field value via reflection | | reflect_set_field | Set a field value via reflection | | reflect_new_instance | Construct a new object instance | | get_class_info | List declared methods and fields of a class | | var_get / var_list / var_delete / var_clear | Manage named variables across calls | | search_javadocs | Search Paper/Folia/Velocity javadoc index | | fetch_javadoc_page | Fetch and strip HTML from a javadoc page |

Fabric client mod (mcp-server-fabric)

| Tool | Description | |------|-------------| | get_chat_log | Recent chat HUD messages | | send_chat_message | Send chat text or /command | | get_player_state | Position, health, inventory, game mode | | player_move_to | Teleport player to coordinates | | player_look_at | Set yaw/pitch or look toward a world point | | player_jump | Trigger a jump | | player_break_block | Break block at coordinates | | player_place_block | Place held item against a block face | | player_interact | Right-click a block | | get_block_at | Block type and state at coordinates | | get_nearby_entities | Entities within a radius | | take_screenshot | Capture client view as base64 PNG | | client_reflect_invoke | Call any client-side method via reflection | | client_reflect_get_field | Read a client-side field | | client_reflect_set_field | Set a client-side field | | client_get_class_info | List methods/fields of a Minecraft class | | client_var_get / client_var_list / client_var_delete / client_var_clear | Variable management |

---

Reflection & variable system

The reflection tools let you call any method on any allowed class and chain results together using named variables:

# Get the overworld World object and store it as $overworld
reflect_invoke(
  class_name="org.bukkit.Bukkit",
  method_name="getWorld",
  args=[{type:"java.lang.String", value:"world"}],
  assign_to="overworld"
)

# Use $overworld to get the player list
reflect_invoke(
  class_name="org.bukkit.World",
  target="$overworld",
  method_name="getPlayers",
  assign_to="players"
)

# Read a field on a non-serialisable object returned as an opaque handle
# (the handle ID looks like "obj_42")
reflect_get_field(
  class_name="org.bukkit.entity.Player",
  field_name="exp",
  target="obj_42"
)

Non-serialisable return values are stored in an in-memory registry and returned as:

{"__type": "object_ref", "__id": "obj_42", "__class": "org.bukkit.World"}

Pass "__id" or "$varName" back as a target or argument value in subsequent calls.

---

Configuration

Paper plugin (plugins/MinecraftMcp/config.yml)

websocket:
  host: "0.0.0.0"
  port: 25575

reflection:
  allowed-packages:
    - "org.bukkit.*"
    - "io.papermc.*"
    - "net.kyori.adventure.*"
    - "net.minecraft.*"
    - "java.util.*"
    - "java.lang.*"
  blocked-packages:
    - "java.lang.Runtime"
    - "java.lang.ProcessBuilder"
  max-object-refs: 1000

Fabric mod (.minecraft/config/mcp.json)

{
  "websocket": { "host": "127.0.0.1", "port": 25576 },
  "reflection": {
    "allowedPackages": ["net.minecraft.*", "com.mojang.*", "net.fabricmc.*"],
    "blockedPackages": ["java.lang.Runtime"],
    "maxObjectRefs": 1000
  }
}

---

Security notes

• The WebSocket servers bind to 127.0.0.1 by default (Fabric) and 0.0.0.0 (Paper — change to 127.0.0.1 if the MCP server runs on the same host).
• Reflection is gated behind configurable package allow/block lists.
• java.lang.Runtime and java.lang.ProcessBuilder are blocked by default.
• The Paper plugin's command sender runs with OP-level permissions; restrict MCP bridge access on shared servers.

---

Development

# Run Paper MCP server (connects to ws://localhost:25575)
npm run dev:paper

# Run Fabric MCP server (connects to ws://localhost:25576)
npm run dev:fabric

# Override the WebSocket URL
PAPER_WS_URL=ws://192.168.1.10:25575 npm run dev:paper

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: InventivetalentDev
• Source: InventivetalentDev/minecraft-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.