langyo/minecraft-mod-mcp

🤖 Connect Your AI to Minecraft

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.

---

What is Minecraft Mod MCP

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

---

Supported Versions

Older versions (1.7.2 – 1.21.10) are available on the releases page.

---

Getting Started

1. Install the Mod

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

2. Install the MCP Bridge

npm install -g minecraft-mod-mcp

Or run without installing:

npx minecraft-mod-mcp

3. Launch Minecraft

Launch the game with your modloader. The mod starts an HTTP server on port 9876 automatically.

4. Connect Your AI

→ 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

5. Using the CLI

→ CLI Usage Guide — launch clients, servers, manage versions, accounts, and build SDKs all from the command line.

---

Usage Tips

Working alongside the mod

Normally, switching away from Minecraft opens the pause screen, which can interrupt MCP commands. Use either method to break free:

• Pause screen: Press Esc to 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+Tab away and the game won’t auto-pause — perfect for working in your IDE or AI tool while the MCP connection stays alive.

Port & HTTP server

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/status returns version, loader, port, pid, uptime — the Node.js bridge uses this to auto-discover the mod on any port
• Open http://localhost:{port}/debug in 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.

Background input mode (driving a client in the background)

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 calling glfwSetCursorPos;
• 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.

---

How It Works

flowchart LR
    A["🧠 AI Tool(Claude Code, Cursor, etc.).mcp.json → stdio"]
    B["🌉 minecraft-mod-mcp bridge(npm package via npx)speaks MCP over stdio"]
    C["🔌 Minecraft Mod MCP(in-game mod)HTTP + SSE server"]
    D["🎮 Minecraft Client(1.7.2 – 26.3)"]

    A  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.

---

Building from Source

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.

---

License

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.