Skip to main content
Glama
InventivetalentDev

minecraft-mcp

by InventivetalentDev
OverviewSchemaRelated ServersScoreDiscussions
Local

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

This server cannot be installed

-
license - not tested
-
quality - not tested
-
maintenance - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/InventivetalentDev/minecraft-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server