Minecraft MCP Server Pro

Fork of yuniko-software/minecraft-mcp-server upgraded into a layered platform for AI control:

• Configurable Minecraft version (default 1.20.1, not hard-pinned)
• Offline / LAN login
• Command channel (/fill, /setblock, batch files) for fast creative builds
• Survival helpers (status / collect / eat; craft tools from upstream)
• Autonomous agent loop (agent-start) — plan → skills → observe

Design: ../docs/superpowers/specs/2026-07-24-minecraft-mcp-pro-design.md

Prerequisites

• Node.js >= 20.10.0
• Minecraft Java LAN world (offline OK)
• Cheats enabled for /fill tools
• MCP client (ZCode, Claude Desktop, …)

Install & run

cd minecraft-mcp-server
npm install
npm run build
npm start -- --username TraeBot --version 1.20.1 --host localhost --port 25565

Dev (tsx):

npm run dev -- --username TraeBot --version 1.20.1

ZCode MCP config example

{
  "minecraft": {
    "type": "stdio",
    "command": "node",
    "args": [
      "./dist/main.js",
      "--host", "localhost",
      "--port", "25565",
      "--username", "TraeBot",
      "--version", "1.20.1"
    ],
    "timeoutMs": 999999
  }
}

Optional: point --batch-root at your workspace so run-command-batch can load minecraft-city-build/command_batches/*.txt:

--batch-root "."

CLI flags

Flag	Default	Meaning
--host	localhost	LAN host
--port	25565	LAN port
--username	LLMBot	Offline name
--version	1.20.1	Mineflayer protocol version (change freely)
--auth	offline	offline | microsoft (v1: use offline)
--capabilities	all	baseline,command,build,survival,agent
--batch-root	parent of cwd	Sandbox for batch file paths
--action-delay-ms	50	Delay between commands
--no-agent	—	Disable agent tools
--max-agent-steps	50	Agent loop limit

New / enhanced tools

Command

• run-chat-command — whitelisted chat commands
• fill-region — auto-split ≤32768
• setblock-at
• clone-region

Build

• build-box — solid / hollow / outline
• clear-region
• run-command-batch — array or file under batch-root
• build-status

Survival / storage / social

• get-player-status / collect-blocks / eat-food / ensure-item
• sleep-nearby — 附近床睡觉过夜
• chest-deposit / chest-withdraw / chest-deposit-all
• find-player / go-to-player / follow-player / fight-nearby / world-time-status
• queue-reset — 卡死队列强制恢复
• (+ upstream craft-item / list-recipes / …)

Blueprint

• build-blueprint — JSON 蓝图（blocks[] 或 palette+layers），见 examples/blueprints/mini-hut.json

Agent (autonomous, near-human) — package 3.11.0

• agent-start — NL goal，如 附近搭石屋 / 建高塔 / 盖别墅 / 修城堡 / 建灯塔 / 跟着我 / 护卫我 / …
• agent-companion — 持续队友模式（靠近→注视→跟随→拾取→探索 循环，直到 agent-cancel）
• agent-status / agent-memory / agent-wait / agent-cancel / agent-chat-control
• 游戏内聊天也可驱动：搭石屋/建塔/别墅/城堡/灯塔/修路/平整/巡逻/护卫 等

Powerful builds (3.11):

• MCP: build-structure + list-structures — templates: tower, villa, castle, lighthouse, pyramid, arena, fountain, road, stairs, platform, wall, hut
• Agent skill: build-structure (same templates, near player)
• Low-level still: fill-region / build-box / build-blueprint / run-command-batch

Agent skills (40+): … + build-structure, pick-up, flatten, patrol, place-bed, pillar-up, clear-lava, mark/go-waypoint

Pathing / creative shortcuts: fly/tp salvage; gather/craft/ensure/minekit creative /give

MCP tools: 54 (incl. build-structure, list-structures, agent-memory)

Reload ZCode MCP after rebuild → pro=3.11.0-dist. Only one TraeBot.

Memory: batch-root/.minecraft-mcp-memory/<bot>.json 记住家坐标等（跨重启）

Reload ZCode MCP after rebuild so the live bot process loads new dist/ (agent plans otherwise stay on old skills). Only one TraeBot process — do not also run node dist/main.js in a terminal.

Offline smoke (before opening the game)

npm run smoke
# or with LAN already open:
npm run smoke -- --host localhost --port 25565 --version 1.20.1

Blueprint example

# after MCP connected + cheats on:
# build-blueprint filePath=examples/blueprints/mini-hut.json
# (batch-root should include this repo, e.g. the repo path or workspace)

Example prompts

Fast creative build

用 fill-region 在我附近清空一块 20x20 地面，再用 build-box 搭一个 10x10x6 白混凝土空心房。

Batch from city builder

run-command-batch filePath=minecraft-city-build/command_batches/xxx.txt（需设置 batch-root）

Autonomous loop

agent-start goal=在附近搭石屋，先保证自己不饿

Version policy

Version is configurable. Default validated target: 1.20.1.
If join fails, try matching your world version: --version 1.20.4 etc.

Safety

Default command blacklist: op, stop, ban, …
Default reject: kill @a / clear @a.
Batch files cannot escape --batch-root.

License

Apache-2.0 (upstream). Pro changes in this fork under the same license terms.