mcdev-mcp

- Live Groovy Execution— Execute Groovy scripts inside the running Minecraft JVM (mc_execute); migrated from Lua in mid-2026
- Game State Snapshots— Player position, health, dimension, time, weather (mc_snapshot)
- Screenshots, Recordings & Screen Inspection— Game-window JPEG, multi-frame contact sheet for temporal debug, and current-GUI structure (mc_screenshot,mc_record_video,mc_screen_inspect)
- World Introspection— Nearby entities and block-entities, plus per-id details (mc_nearby_entities,mc_entity_details,mc_nearby_blocks,mc_block_details,mc_looked_at_entity)
- Visual Markers— Outline entities or blocks for the user to spot (mc_set_entity_glow,mc_set_block_glow,mc_clear_block_glow)
- Item Texture Rendering— Render an inventory slot, an item id, or a slot on another entity as PNG (mc_get_item_texture,mc_get_item_texture_by_id,mc_get_entity_item_texture)
- Chat History— Recent client-side chat messages (mc_chat_history)
- Session Control & Dev Loop— Join/leave servers, quit the client, and reconnect after a relaunch (mc_join_server,mc_leave_server,mc_quit_client,mc_wait_for_bridge,mc_wait_until_in_world; gated bysession_control_enabledin the DebugBridge config). Build/launch orchestration is the coding agent's job, guided by themcdev://guides/dev-loopresource and theminecraft-dev-loopskill.
- Slash Commands— Execute in-game commands (mc_run_command, opt-in dev tool)
- Script Execution Logs— Review pastmc_executeruns and error patterns (mc_script_logs, opt-in via Claude Desktop user setting)

- mcdev://guides/python-scripting— Wire-protocol reference for AI agents that want to drive DebugBridge from Python directly (bypassing the MCP tools): WebSocket framing, a minimal asyncio client, and the Groovy surface you send through it. Surfaced via the standard MCPresources/list+resources/read, with a pointer in the server'sinstructionsso agents know to look.

Security note —initis intentionally terminal-only.The MCP server only exposes read/query tools. Downloading and decompiling Minecraft sources must be triggered by you in the terminal; an AI agent connected to the server has no tool surface to triggerinit,rebuild,clean, orcallgraph.

# Download, decompile, and index Minecraft sources (~2-5 minutes) npx mcdev-mcp init -v 1.21.11

- Downloads the Minecraft client JAR
- Decompiles using Vineflower (pure Java, 8 threads)
- Builds the symbol index (classes, methods, fields, inheritance)
- Generates call graph formc_find_refs

Codex can launch local stdio MCP servers directly. Install the published package with:

codex mcp add mcdev-mcp -- npx -y mcdev-mcp serve

If you are developing from a local checkout, build first and point Codex at the local server:

git clone https://github.com/use-ai-for-mc/mcdev-mcp.git cd mcdev-mcp npm install npm run build codex mcp add mcdev-mcp -- node "$(pwd)/dist/index.js"

Restart Codex Desktop, or start a new Codex session, after adding the server. Codex will launch the MCP server automatically when a session needs it; you do not runserveby hand.

# Skip callgraph generation if you don't need mc_find_refs npx mcdev-mcp init -v 1.21.11 --skip-callgraph # Generate callgraph later npx mcdev-mcp callgraph -v 1.21.11

Note:mc_version(withaction: "set") must be called before using any other static MCP tools. If the version isn't initialized, the AI will be instructed to ask you to runinit.

git clone https://github.com/use-ai-for-mc/mcdev-mcp.git cd mcdev-mcp npm install npm run build # Use the local build instead of npx node dist/cli.js init -v 1.21.11 node dist/cli.js serve # stdio MCP server; MCP clients launch this

Upgrading from an older version?If you have a previous installation using DecompilerMC, runnpx mcdev-mcp clean --allfirst to remove old cached data.

Before using static tools, set the active Minecraft version:

Manage the active Minecraft version. Call withaction: "set"before other static tools, oraction: "list"to see what's initialized.

{ "action": "set", "version": "1.21.11" }

{ "action": "list" }

Search decompiled source code for classes, methods, or fields by name pattern.

{ "query": "Minecraft", "type": "class" }

Get the full decompiled source code for a class.

{ "className": "net.minecraft.client.Minecraft" }

Get source code for a specific method with context.

{ "className": "net.minecraft.client.Minecraft", "methodName": "tick" }

Find who calls a method (callers) or what it calls (callees).

{ "className": "net.minecraft.client.MouseHandler", "methodName": "setup", "direction": "callers" }

Note:Requires callgraph to be generated (included ininitby default).

List all classes under a specific package path (includes subpackages).

{ "packagePath": "net.minecraft.client.gui.screens" }

List all available packages. Optionally filter by namespace.

{ "namespace": "minecraft" }

Find classes that extend or implement a given class or interface.

{ "className": "net.minecraft.world.entity.Entity", "direction": "subclasses" }

Connect to a running Minecraft instance. Other runtime tools auto-connect if needed. Passreset: trueto disconnect and clear state before reconnecting (useful when switching instances). Ifportis omitted, scans ports 9876-9886.

{ "port": 9876, "reset": false }

Execute Groovy code in the running game. The binding persists across calls, andmc/player/levelare pre-bound. (The runtime migrated from Lua to Apache Groovy 5 in mid-2026 — the tool description carries a Lua→Groovy cheat-sheet.)

return player.blockPosition().toShortString()

Get a structured snapshot of current game state (player, world, time, weather).

Capture the game window as a JPEG file and return its path.

{ "downscale": 2, "quality": 0.75 }

Capture a short burst of frames for debugging temporal rendering issues (animation glitches, shader bugs, particles, sub-tick artifacts a single screenshot can't resolve). Returns either one composed grid JPEG (default) or N separate frame JPEGs.

{ "frames": 60, "interval": 50, "output": "grid", "downscale": 2, "quality": 0.75 }

intervalis either"frame"(every render tick, ~60 Hz) or milliseconds (number, >= 1). Numeric intervals (50–100 ms) are recommended unless you specifically need sub-tick detail; at"frame"cadence the encoder may fall behind and the response'sdroppedcount tells you how many frames were skipped. Capped at 300 frames per call. Files land under<gameDir>/debugbridge-recordings/<requestId>/.

Snapshot the screen the player currently has open (chest UI, inventory, advancement screen, etc.) and return its structure.

SetincludeIcons: trueto render each unique item in the screen as a small PNG and attach an icons map keyed by registry id.

Get the most recent client-side chat messages — what the user has seen in chat.

{ "limit": 50, "includeJson": false }

SetincludeJson: trueto include each message's full MinecraftComponentJSON (useful when chat-message styling matters).

List entities (mobs, items, projectiles, players) within a radius of the player.

{ "range": 64, "limit": 100, "includeIcons": false }

Returns each entity's id, type, position, and primary equipment summary. Pass theidtomc_entity_details,mc_set_entity_glow, ormc_get_entity_item_textureto drill in.

Get full details for one entity by id (theidfield returned bymc_nearby_entitiesormc_looked_at_entity).

Returns the entity id the player is currently aiming at (raycast), ornullif nothing is in the line of sight.

List nearby block-entities (signs, chests, banners, beacons, hoppers, …). Plain world blocks aren't included — usemc_block_detailsfor any specific position.

{ "range": 16, "limit": 100 }

Get details for the block-entity at(x, y, z): sign lines, chest contents, banner patterns, etc.

{ "x": 100, "y": 64, "z": 200 }

Outline an entity with the team-colour glow so the user can spot it. Passglow: falseto remove.

{ "entityId": 12345, "glow": true }

Highlight a block in the world (yellow outline on 1.19, vanilla glow on newer versions). Passglow: falseto remove just this position.

{ "x": 100, "y": 64, "z": 200, "glow": true }

Clear all block highlights set viamc_set_block_glowin one call.

Render the item in the player's inventory slot N as a PNG attached as MCP image content.

Render the default texture for a registry id (e.g.minecraft:diamond) without needing the item to be in any inventory.

{ "itemId": "minecraft:diamond" }

Render an item carried by another entity.slotis"mainhand","offhand", or one of the armor slot names.

{ "entityId": 12345, "slot": "mainhand" }

These five tools are the bridge-side primitives of the rebuild → relaunch → rejoin loop. The underlying endpoints (disconnect,joinServer,quit) aredisabled by default: set"session_control_enabled": truein<minecraft>/config/debugbridge.jsonand restart the client (the flag is read at startup).mc_connectreports whether the connected instance has it enabled, and the tools return exact instructions when it's off.