Minecraft Mod MCP
AI-powered mod development toolkit — build, test, and debug Minecraft mods with AI
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add minecraft-mod-mcp -- npx -y minecraft-mod-mcp@0.4.28在終端機中執行。
{ "mcpServers": { "minecraft-mod-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
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.
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.
npm install -g minecraft-mod-mcp
Or run without installing:
npx minecraft-mod-mcp
Launch 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:
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.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.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 porthttp://localhost:{port}/debug in your browser for a live dashboard with MCP logs, SSE events, and connection statusThe 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.
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:
xpos/ypos) instead of calling glfwSetCursorPos;java.awt.Robot, whose injected clicks/keystrokes would land on whatever window is actually in front.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:
at your option.
MCP server bridge & launcher CLI for Minecraft — connect AI tools to Minecraft via Model Context Protocol, launch and manage instances
{ "mcpServers": { "minecraft-mod-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Minecraft Mod 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 MCP server bridge & launcher CLI for Minecraft — connect AI tools to Minecraft via Model Context Protocol, launch and manage instances