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, capture video frames
| MC Version | Forge | Fabric | NeoForge |
|---|---|---|---|
| 26.1.2 | ⬇ | — | ⬇ |
| 1.21.11 | ⬇ | ⬇ | ⬇ |
Older versions (1.7.2 – 1.20.6) 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.1.2
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:
- The game prints
[MCP-MOD] Debug page: http://127.0.0.1:{port}/debugto the console - A clickable chat message with the debug page URL appears in-game
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.
📸 Screenshot — click to expand
flowchart LR
A["🧠 AI Tool<br/>(Claude Code, Cursor, etc.)<br/>.mcp.json → port 9876"]
B["🔌 Minecraft Mod MCP<br/>(in-game mod)<br/>HTTP + SSE server"]
C["🎮 Minecraft Client<br/>(1.8.9 – 26.1.2)"]
A <-- "HTTP / SSE" --> B
B -- "reflection" --> C
The mod runs an HTTP server on port 9876 inside Minecraft. Your AI tool connects via the standard MCP protocol (SSE transport), and every command — click, type, screenshot, etc. — uses Java reflection to 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.