AI-powered mod development toolkit — build, test, and debug Minecraft mods with AI
English • 简体中文 • 繁體中文 • 日本語 • 한국어 • Français • Español • Русский
Copy this link and paste it to your AI agent — it will configure itself automatically:
https://github.com/langyo/minecraft-mod-mcp/blob/master/docs/guides/en/AI-TOOLS.md
Your AI reads the guide, sets up the MCP connection, and starts controlling the game. No manual config needed.
Already have the mod installed? That one link is all you need.
Minecraft Mod MCP is a mod designed for AI-assisted mod development. It exposes Minecraft's internals to AI tools via the MCP protocol, letting your AI agent inspect screens, click through GUIs, and run commands — perfect for testing mods, verifying behavior, and automating repetitive workflows.
Built for mod developers — test your GUIs, verify block/item behavior, and run smoke tests on new features.
- See — capture screenshots with coordinate grids
- Act — click, type, scroll, drag, and press any key
- Know — query player position, world info, screen buttons, and debug fields
- Record — stream events in real time via SSE
| MC Version | Forge | Fabric | NeoForge |
|---|---|---|---|
| 26.2 | ⬇ | ⬇ | ⬇ |
| 26.3 | ⬇ | ⬇ | ⬇ |
| 26.1.2 | ⬇ | — | ⬇ |
| 1.21.11 | ⬇ | ⬇ | ⬇ |
Older versions (1.7.2 – 1.21.10) are available on the releases page.
Download the JAR from GitHub Releases and place it in your Minecraft mods folder.
- Requires Forge, Fabric, or NeoForge (see supported versions above)
- Works with Minecraft 1.7.2 through 26.3
npm install -g minecraft-mod-mcpOr run without installing:
npx minecraft-mod-mcpLaunch the game with your modloader. The mod starts an HTTP server on port 9876 automatically.
→ AI Tool Integration Guide — step-by-step for Claude Code, Cursor, Cline, Copilot, and 20+ other AI tools.
Or paste this link to your AI agent and let it handle the setup:
https://github.com/langyo/minecraft-mod-mcp/blob/master/docs/guides/en/AI-TOOLS.md
→ CLI Usage Guide — launch clients, servers, manage versions, accounts, and build SDKs all from the command line.
Normally, switching away from Minecraft opens the pause screen, which can interrupt MCP commands. Use either method to break free:
- Pause screen: Press
Escto open the pause screen, then click the MCP overlay's release mouse button. This lets you switch windows freely without re-triggering the pause screen. - In-game overlay: In the 3D view, click the MCP overlay button in the top-right corner to temporarily detach the mouse cursor. Once released, you can
Alt+Tabaway and the game won't auto-pause — perfect for working in your IDE or AI tool while the MCP connection stays alive.
The mod starts an HTTP server when the game loads. It tries port 9876 first; if occupied it falls back through 9875 → 9874 → ... → 9000 until it finds a free one. Set a fixed port with -Dmcp.port=XXXX (JVM arg) or MC_MCP_PORT (env).
To confirm which port the mod chose:
GET /api/statusreturnsversion,loader,port,pid,uptime— the Node.js bridge uses this to auto-discover the mod on any port- Open
http://localhost:{port}/debugin your browser for a live dashboard with MCP logs, SSE events, and connection status
The version and loader (Forge/Fabric/NeoForge) are confirmed at handshake via /api/status so both the bridge and the debug page know exactly which mod environment they're talking to.
The mod's HTTP API drives the game's input, so it is locked down by default:
- Loopback only. The server binds
127.0.0.1and, while bound there, rejects anyHostheader other than127.0.0.1,localhostor[::1](DNS rebinding). To deliberately expose it on your LAN, set-Dmcp.bind=0.0.0.0(JVM arg) orMC_MCP_BIND(env) together with a token; without one the mod stays on loopback. - Shared bearer token. When a token is configured with
-Dmcp.token=...orMC_MCP_TOKEN,/api/cmd,/api/screenshot,/api/eventsand/api/callsrequireAuthorization: Bearer <token>;/api/statusstays open for port discovery. The bundled launcher always sets one for the game it launches: it usesMC_MCP_TOKENfrom its own environment if present, otherwise a random token kept in the owner-only filemcp_launcher/mcp-token, and hands it to the game via the environment (never the command line). The bridge sends the same token automatically. A mod jar the launcher installs into a dedicated server'smods/runs with the tokenless loopback default unless you exportMC_MCP_TOKENfor that server yourself. For the debug dashboard, openhttp://localhost:{port}/debug?token=<token>. - JSON only.
POST /api/cmdrequires the media typeapplication/json, so web pages cannot fire commands at the local API with cross-origin form posts. - Command whitelist. Only the documented commands are dispatched; anything else is rejected before reaching a handler.
- Control-mode consent.
enter_control_modecan only be called remotely when the game was launched with-Dmcp.remote_control=true(orMC_MCP_REMOTE_CONTROL=1); the bundled launcher sets this, since launching through it is your consent to agent control. In a game you launched yourself, take over in game instead (Esc→ MCP Take Over).
Mod jars downloaded by the launcher are pinned to the release matching the bridge version and verified against the sha256 digest GitHub publishes for each release asset. If that release was never published, or GitHub cannot be reached, the launcher warns on stderr and falls back to a previously downloaded jar of another version, or to the latest stable release (verified the same way) when the tag does not exist and nothing is cached.
On Windows, a Minecraft window launched by a background process still counts as "focused" to GLFW, so while an agent drives the client the mod's cursor moves (glfwSetCursorPos) and cursor locking (GLFW_CURSOR_DISABLED) would move and confine your real desktop cursor, even though the game window stays behind your other windows.
If an agent or CI drives the client while you keep working, enable background input mode with -Dmcp.background_input=true (JVM arg) or MC_MCP_BACKGROUND_INPUT=1 (env). In this mode the mod:
- only edits Minecraft-internal mouse state (window-local
xpos/ypos) instead of callingglfwSetCursorPos; - never locks or confines the OS cursor when entering/leaving MCP control mode, and releases any confinement vanilla itself applies;
- never falls back to
java.awt.Robot, whose injected clicks/keystrokes would land on whatever window is actually in front.
While MCP control mode is active, pressing Esc would normally open the pause screen and pause the game out from under the agent. On the legacy clients (1.7.2–1.12.2) the mod therefore cancels the pause menu while control mode is active; when control mode exits, the pause menu is re-opened so your screen is never swallowed. If you prefer vanilla pause behavior, disable the cancellation with -Dmcp.suppress_pause_menu=false (JVM arg) or MC_MCP_SUPPRESS_PAUSE_MENU=false (env). On modern clients the pause behavior is handled by the game itself and this switch has no effect.
📸 Screenshot — click to expand
flowchart LR
A["🧠 AI Tool<br/>(Claude Code, Cursor, etc.)<br/>.mcp.json → stdio"]
B["🌉 minecraft-mod-mcp bridge<br/>(npm package via npx)<br/>speaks MCP over stdio"]
C["🔌 Minecraft Mod MCP<br/>(in-game mod)<br/>HTTP + SSE server"]
D["🎮 Minecraft Client<br/>(1.7.2 – 26.3)"]
A <-- "MCP / stdio" --> B
B -- "HTTP" --> C
C -- "reflection" --> D
The mod runs an HTTP server on port 9876 inside Minecraft. Your AI tool talks MCP over stdio to the minecraft-mod-mcp bridge, which forwards every command — click, type, screenshot, etc. — to the mod; Java reflection makes it work across all Minecraft versions without version-specific code.
This section is for contributors. If you just want to use the mod, see Getting Started above.
See CONTRIBUTING.md for development setup, project structure, and guidelines.
Licensed under any of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
- CC0 1.0 Universal (LICENSE-CC0 or http://creativecommons.org/publicdomain/zero/1.0/)
at your option.