BlockHand — Minecraft Education MCP

Gives AI hands and feet in Minecraft Education Edition: actions (Agent movement, mining, placing, tilling, transporting), eyes (block sensing, coordinate queries, game event subscriptions), creation (ten geometric shapes and per-cell blueprints).

Operates through Minecraft Education's officially documented /wsserver connection command (/connect is an alias) — no process injection, no game file modification, no screen recognition. The connection command is an official interface; the subsequent WebSocket message protocol has no public stability guarantee, so re-verification is needed after game updates.

• 42 tools, 2 resources

• 216 unit and integration tests, 1 stdio/process lifecycle smoke test that doesn't require launching the game, 1 live verification on a real device

• No account, token, or secret required; the MCP runtime binds only to loopback and writes no game files or artifacts

1. Getting Started in Three Steps

Step One: Install and Build on Each Machine

cd /你的路徑/minecraft-edu
corepack pnpm install --frozen-lockfile
corepack pnpm run build

Node must be 22.23.1 as specified in the project's .nvmrc; pnpm is pinned to 11.17.0 by Corepack. Dependencies must be installed locally on both Windows and Mac; do not copy node_modules from another operating system. Minecraft Education currently requires macOS 14 as the minimum on Mac.

Step Two: Register MCP Once on That Machine

Supports Codex／Claude Code／Gemini CLI／Grok CLI, identical on Windows and macOS.

First, Get Two Absolute Paths

Absolute paths are mandatory when registering — writing just node is not enough. Desktop AI tools are launched by Finder/File Explorer and cannot read nvm, Homebrew, or PATH from your shell; writing node may pass when tested in a terminal, but the desktop version will fail to start, and the error message usually just says "server didn't respond," which is hard to debug.

macOS:

node -p "process.execPath"   # Node 絕對路徑
pwd                          # 專案絕對路徑（在 minecraft-edu 目錄下執行）

Windows (PowerShell):

node -p "process.execPath"
(Get-Location).Path

Below, <NODE> represents the absolute Node path and <REPO> the absolute project path. The server entry point is always <REPO>/dist/index.js (written as <REPO>\dist\index.js on Windows). Quote the entire path if it contains spaces.

Using the Installer (Supported by All Four, Recommended)

corepack pnpm run setup:codex     # 或 setup:claude / setup:gemini / setup:grok
corepack pnpm run doctor          # 加 --client=claude 等可診斷其他家

The installer doesn't just write commands into a config file; it:

• Auto-fills the absolute Node path for this machine, without relying on whether the desktop app can read nvm, Homebrew, or the shell PATH.

• Runs a real MCP initialize first (using the command/args/env about to be written) to confirm all 42 tools are present before touching any persistent settings. A stale dist, a wrong launcher, or a non-executable Node will fail before anything is written.

• Does nothing when already correctly registered — re-running is safe.

• Stops and lists the differences when a same-named but incompatible entry exists, without auto remove/add, to avoid overwriting someone else's timeout, tool policy, or another clone's settings.

• Writes only through each vendor's official mcp add／mcp remove subcommands, never by hand-editing config files — that would bypass each vendor's own schema validation and scope resolution.

Removal uses corepack pnpm run uninstall:codex (or uninstall:claude, etc.). It also has accidental-deletion protection: it refuses entries not recognizable as belonging to this working tree.

Write locations and restart requirements per vendor:

Read strategies differ: Codex and Grok have mcp list --json, so machine-readable output is used directly. Claude Code and Gemini's list only produce human-readable text without env, so compatibility cannot be determined from it; instead, their official CLI's just-written config files are read read-only. Writes always go through the CLI.

Manual Commands (When You Don't Want the Installer)

The commands are equivalent, but you must fill in the absolute paths yourself, and there's no upfront initialize validation or overwrite protection.

codex  mcp add minecraft-edu --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
claude mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
gemini mcp add minecraft-edu <NODE> <REPO>/dist/index.js --scope user --env MINECRAFT_EDU_WS_PORT=19131
grok   mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js

Three easy-to-miss differences:

• Gemini's command and args are positional parameters, placed after the name, with no -- separator.

• Gemini's default scope is project; you must explicitly write --scope user for global availability.

• Claude's default scope is local (only effective in the current directory); --scope project writes to the project root's .mcp.json, which can be shared with the repo — use this when sharing with a whole class.

Hand-Editing Config Files (Fallback When the Installer Fails)

Claude Code and Gemini CLI use JSON:

{
  "mcpServers": {
    "minecraft-edu": {
      "command": "<NODE>",
      "args": ["<REPO>/dist/index.js"],
      "env": { "MINECRAFT_EDU_WS_PORT": "19131" }
    }
  }
}

Codex and Grok CLI use TOML:

[mcp_servers.minecraft-edu]
command = "<NODE>"
args = ["<REPO>/dist/index.js"]
env = { MINECRAFT_EDU_WS_PORT = "19131" }

Windows Notes

• The absolute Node path is usually C:\Program Files\nodejs\node.exe; with nvm-windows it looks like C:\Users\<you>\AppData\Roaming\nvm\v22.23.1\node.exe.

• Backslashes in JSON config files must be escaped: "C:\\Program Files\\nodejs\\node.exe". TOML can use single-quoted literal strings instead: command = 'C:\Program Files\nodejs\node.exe'.

• If Minecraft Education is the Microsoft Store UWP version, loopback will be blocked by Windows app isolation and requires an additional CheckNetIsolation LoopbackExempt exemption (see Section 8).

After Registration

Fully quit and restart the AI tool — the desktop version must actually terminate, not just close its window. Then confirm with doctor (doesn't touch Minecraft, doesn't change settings):

corepack pnpm run doctor

It checks the Node version, build artifacts, platform requirements, and registration status, and runs another MCP initialize using the actually registered command/args/env, so a config pointing to a dead Node can't pass as green. Add --json for structured output. You can also ask each vendor's CLI directly:

codex mcp list
claude mcp list
gemini mcp list
grok mcp list

Or simply have the AI call mc_status — if it returns a connectCommand, the server can start.

Each machine must be registered once individually: Windows laptops, Macs, and other computers all have different Node and project absolute paths, so settings cannot be copied between them. On the same machine, the desktop/CLI/IDE versions of the same tool share the same settings.

Step Three: Connect Manually in the Game

corepack pnpm run connect

This compatibility entry point only displays instructions — it does not launch Minecraft, switch foreground windows, or simulate keystrokes. Windows PowerShell auto-input has been removed; Mac also does not add AppleScript automation.

It's easy to get the direction backwards: the game is the one connecting out; the MCP server is the one being connected to.

1. In the current AI conversation, call mc_status and copy the connectCommand it returns.

2. Open Minecraft Education and enter a world (staying on the main menu does nothing).

3. The world must have Cheats enabled, and the operator needs Admin/OP permissions.

4. Type manually in the chat bar, for example:

/connect 127.0.0.1:19131

You're done when you see Connection established. After that, just tell the AI "help me build a hollow glass sphere in front of me."

To reconnect, you don't need to retype the whole string: press T in the chat bar, then ↑ to recall the previous command, then Enter.

Early versions had a bug where connections would drop after about 60 seconds of idling: the heartbeat only recognized WebSocket pong frames, but Bedrock/Education clients never send pongs, so healthy connections were killed by their own heartbeat. This is now fixed (liveness is determined by any incoming packet, supplemented by application-layer probing), and idling should no longer cause disconnects. If it still drops, first confirm you're running a rebuilt dist/.

Don't memorize 19131: when desktop, CLI, IDE, or multiple tasks start simultaneously, later-started MCP instances may get different free ports. Always use the command reported by the task you're currently operating.

Related MCP server: Minecraft MCP Bot

2. Real-Device Verification

First, run the safe diagnostics that don't require launching the game:

corepack pnpm run doctor
# 機器可讀版本
corepack pnpm blockhand doctor --json

doctor doesn't modify persistent settings or start Minecraft; it briefly creates an isolated loopback socket to verify the launcher, 42 tools, 2 resources, stdio EOF, and listening port release, and completes another initialize using Codex's actually registered command/args/env, so a config pointing to a dead Node can't pass as green.

Once the game is open, the world is loaded, and cheats are enabled:

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run live

The script prints the /connect command to enter, waits for you to connect, then walks a complete path and reports PASS/FAIL for each item: connect → read player coordinates → speak in-game → set time → summon Agent → sense → walk an L-shaped path → preview build → build a hollow glass sphere → verify the blocks actually exist → merge blueprints → subscribe and receive events → policy gate → clean up the demo build.

After Game Updates

Reading blocks (mc_read_block) relies on the text format of testforblock's failure message, and that format has no official stability guarantee. If Minecraft Education silently auto-updates and changes the wording, or the game language is switched to something other than Traditional Chinese/Simplified Chinese/English, this path will break.

The failure is silent: the tool won't break; it will just start saying "can't read." So this project deliberately does not make it a routine check in every live run — routine checks build the habit of relaxing when you see a green light, but the real moment for judgment is "when behavior becomes suspicious," not the one fixed run per week.

Instead, judge proactively when needed:

mc_verify_reading  { position: 任一座標 }

It sends at most two commands, writes nothing to the world, and returns parseable:

• true → the parsing path is normal and mc_read_block results are trustworthy.

• false → the protocol has drifted. In this case mc_read_block always returns an error rather than null (see Section 3), so no one can mistake "can't read" for "it's empty there." The returned raw is the game's original message; compare it against PATTERNS in src/domain/block-report.ts to see which pattern needs to be added.

Three signals that make you want to run it:

1. mc_read_block starts returning errors, but you can see in the game that the cell clearly has something in it.

2. The game just updated, and you're about to do anything that depends on reading (grading, symmetry analysis).

3. The game language was changed.

The server instructions also contain the same clue, so the AI will find this tool on its own when behavior looks suspicious — you don't need to remember to remind it.

By default, the demo build is filled back with air, leaving no litter in the world. To keep it for inspection:

cd gjlmotea/vibe/mcp/minecraft-edu && node scripts/live-check.mjs --keep

Verification that doesn't require launching the game (types, tests, build, stdio handshake, STDIN-close port release, and port-occupied failure all run in one pass):

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run verify

3. Tool Surface

Connection and Fallback (4)

Agent — Hands and Feet (10)

Agent direction is relative to its own facing, not world orientation.

World (13)

mc_set_block, mc_fill, mc_clone, mc_test_block, mc_read_block, mc_verify_reading, mc_compare_regions, mc_analyze_symmetry, mc_query_target, mc_summon, mc_world_settings (time/weather/game rules/difficulty), mc_structure (save/load structures), mc_ticking_area.

mc_query_target parses the JSON string returned by querytarget — this is the proper way to get player or Agent coordinates. Ask it before building.

Reading has inherent limitations, and it's better to state them clearly than to pretend they don't exist. Education has no "read any block" command, so:

• mc_test_block is a yes/no question: you have to guess a block ID first.

• mc_read_block doesn't require guessing — it uses air as a sentinel to ask, and when the guess is wrong, the game message reveals the actual block. But what it returns is a localized display name ("dirt" in Chinese) rather than a block ID (dirt), so it can't be fed back into mc_set_block. When parsing fails, this tool returns an error, not a successful response with null — the reason is below.

• mc_verify_reading proactively verifies that the parsing path above still works. Run it once before class to know whether mc_read_block results can be trusted.

• mc_compare_regions compares an entire region with a single testforblocks. Per-cell comparison hits host timeouts beyond a few hundred cells; this one doesn't. masked mode ignores source air, which suits checking "whether the things that should be there are there" regardless of extra surroundings — grading student work is exactly this shape.

Why a parse failure returns an error rather than null

Because the user of this tool is an AI, and an AI doesn't suspect the system is broken.

A "successful" response with block: null is easily read as "read it, it's empty there." The AI will then very confidently continue based on this wrong belief — for example, overwriting a student's entire class-period work as if it were empty ground, with no error record to trace afterward. A human seeing null would find it odd and stop to debug; an AI won't.

An error can't be consumed as data and continued on. That's the point.

mc_verify_reading is the other half: it doesn't need to know what's in the cell in advance — if the cell is air, it asks with bedrock (air can't be bedrock, guaranteeing a mismatch) to force a failure message; if the cell has something, the first question already yields a message. Both paths guarantee a message, at most two commands, and nothing is written to the world.

This defense line is guarded by mutation tests: deliberately breaking the parsing rules must turn 7 probe-and-parser tests red.

For reading an entire region cell by cell, use behavior packs and the Script API; this project deliberately avoids that path because it would add an extra installation step on school computers.

Iterating on the Same Building

mc_structure's saveMode is designed exactly for this:

Version management is just naming: castle_v1, castle_v2. Same name overwrites directly; change the name before changing versions.

The game has no "list saved structures" command, so what's been saved can only be tracked by name. The bridge remembers the names saved during the current connection — ask mc_status to see them — but that only covers this process and is gone after restart (the disk-mode files remain; you have to remember the names yourself).

Symmetry Analysis — Grading Work

mc_analyze_symmetry checks whether a region is mirror-symmetric, and when it isn't, it points out which cells are asymmetric rather than just returning a "no."

How it works: testforblocks only does translation comparison, not mirroring, so the region is first saved with structure save, then loaded with the mirror parameter into a scratch area, and the two regions are compared. A full pass scores 100%; only on failure does it break down into n³ per-cell comparison, with the score being the proportion of matching cells.

This tool temporarily writes to the world, and the flow below leaves no mess if any step fails:

1. Save the analysis region — abort on failure (usually an unloaded chunk).

2. Back up the scratch region first — abort on backup failure, and never place the mirrored copy, leaving the world untouched.

3. Place the mirrored copy and compare.

4. Restore the scratch region and delete the scratch structure regardless of success or failure; the restore result is truthfully reported in scratchRestored, with no whitewashing on failure.

The scratch region must not overlap the analysis region, or the mirrored copy would overwrite the original building — this check happens before any command is sent.

Player and Feedback (7)

mc_teleport, mc_give, mc_gamemode, mc_effect, mc_player_action (kill／clear／xp／ability), mc_message (say／tell／title／subtitle／actionbar), mc_feedback (sound／particle).

Building (4)

Events — Perception (4)

mc_events_catalog, mc_events_subscribe, mc_events_unsubscribe, mc_events_poll.

Events go into a ring buffer, read continuously with a cursor; dropped > 0 means polling is too slow and some events will never be read. Subscriptions are automatically re-established after reconnection.

4. Why Building Doesn't Freeze

The naive approach sends one setblock per block. A solid sphere of radius 20 has over 33,000 cells — over 30,000 WebSocket round trips, which in practice is equivalent to freezing.

BlockHand's pipeline is:

形狀參數 → inside() 判定掃描 → 方塊座標集合
        → X 連段合併 → Z 矩形合併 → Y 立方合併（三階段 greedy）
        → 依 Bedrock 單次 /fill 上限 32768 拆批
        → 送出

A solid sphere of radius 8 is compressed from over 2,000 blocks to fewer than 200 commands, and the merge result is deterministic — the same input always yields the same batches, so tests pin down that "the set of blocks covered after merging must be exactly identical to the original point set," with neither over- nor under-coverage.

Hollow shapes are always implemented via "interior test + shell neighbor test" rather than a separate hollow math for each shape. Adding a new shape only requires writing inside(), and hollow behavior is automatically consistent.

5. Safety Boundaries

What it doesn't do

• No external network: the WebSocket listener only opens on 127.0.0.1.

• The MCP runtime writes no host files: there is no artifact output path. Only when the user explicitly runs setup:<client>／uninstall:<client> does that vendor's official CLI update local MCP settings.

• One exception to be clear about: mc_structure with saveMode="disk" writes structure files through the game into Minecraft's world folder. That's not the MCP runtime writing files, but it does leave something on the user's disk. So the default is memory (temporary, gone when the game closes); disk should only be used when the user explicitly asks to keep something, and the tool reply always states where it wrote — no silent file drops.

• No secrets: the entire project has no tokens, accounts, or credentials.

• No proactive connections: if the game doesn't /connect in, all tools return actionable error messages rather than failing silently.

The mc_run_command gate

Architecture principle 4 in mcp/README.md requires rejecting arbitrary execution entry points. The judgment here: slash commands operate entirely within the local game world, never touching the host filesystem, processes, or network, so they don't equal arbitrary code execution. What must actually be blocked are operations that would break the bridge, so the policy is structural rather than a keyword blacklist guessing intent:

1. Only single lines are allowed — newlines and NUL are rejected outright; \n can't split one request into two commands.

2. wsserver and connect are rejected — they would point the game at a different endpoint, breaking all tools afterward.

3. Other commands are tagged with read-only／world-write／wide-effect risk levels, leaving it to the MCP Host to decide, per annotations, whether human confirmation is needed.

All block IDs, selectors, and state strings that get interpolated into command lines pass through a whitelist regex first, preventing whitespace from being used to smuggle in extra arguments.

Classroom protection (on by default)

Point 3 above delegates the decision to the Host, which works in solo development, but this project's use site is a classroom:

• The Host may be set to auto-approve — teachers do this easily for smooth class flow.

• Any student who can talk to that AI can effectively issue commands. They don't need to break the bridge; they just need to persuade the model.

• Misuse doesn't even need raw commands: mc_player_action natively accepts @a and kill is one of its options. So blocking only raw commands is theater; both paths must be blocked.

The rule is shaped into a sentence a teacher can teach: actions that affect "people" must name them individually.

"Kill the whole class" thus goes from a single sentence to having to name each student individually, while legitimate classroom management (clearing one student's inventory) is completely unaffected.

To disable, set MINECRAFT_EDU_CLASSROOM_GUARD=0 — the error message itself tells you this, so no one thinks the tool is broken.

Trademark

Per the Minecraft Usage Guidelines, third-party tools must not look like official products. The product name BlockHand deliberately contains no Minecraft trademark; minecraft-edu is merely a descriptive folder name within this private workspace. If this is ever released publicly, the package name and any public exposure must be re-reviewed.

6. Settings

All variables have defaults; .env is not required.

7. Module Map

src/
  domain/                     純資料與純邏輯，不依賴 MCP、ws 或 Node
    contracts.ts              型別、已知事件名、Bedrock fill 上限
    coordinates.ts            絕對／相對／局部座標格式化與邊界檢查
    commands.ts               所有 slash 指令建構器 + 注入白名單
    command-policy.ts         raw 指令的結構性閘門
    build/shapes.ts           十種形狀；inside() + 外殼鄰居測試
    build/fill-planner.ts     三階段 greedy 合併 + 依上限拆批
  ports/minecraft-connection.ts   連線抽象；測試靠它塞假件
  adapters/ws-minecraft-connection.ts  WebSocket 監聽、requestId 對應、事件緩衝、重連重訂閱
  application/
    blockhand-service.ts      Agent 程式展開、querytarget 解析、事件
    build-service.ts          規劃與執行分離（先讀後寫）
  server/
    create-server.ts          server 實例與給 Host 的操作指引
    schemas.ts                共用 zod 片段
    tool-kit.ts               回應塑形與錯誤包裝
    tools/                    session／agent／world／player／build／event
  composition.ts              組裝；可注入假連線
  index.ts                    stdio 入口

The domain layer is completely unaware of WebSocket, so the entire MCP tool pipeline can be tested end-to-end with pure in-memory fakes—the 16 tests in tests/integration/mcp-client.test.ts don't require launching the game.

8. Known Limitations

• The world must have cheats enabled, otherwise the game rejects every command. This is a Minecraft rule, not a bug.

• macOS has been live-verified on real hardware (Claude Code path): On 2026-08-25, /connect, heavy read/write (over 45,000 blocks in a single session, including fill/setblock/testforblock/teleport), and the full disconnect-reconnect flow were completed on macOS via Claude Code. Not yet verified is the launch path of "starting Codex Desktop from Finder"—GUI launches inherit PATH and environment variables differently and still need individual testing.

• Agent is exclusive to Education Edition; the regular Bedrock edition doesn't have this feature.

• Event names and agent subcommands are not officially documented by Mojang; they come from public observation, and game updates may change behavior. mc_events_subscribe allows names outside the list but marks them as unverified.

• The argument order of agent setitem is unconfirmed; no dedicated tool has been made for it yet. When needed, use mc_run_command.

• @s may not resolve under WebSocket commands: commands sent through the bridge have no entity identity, and in practice querytarget @s returns no response at all. mc_query_target therefore defaults to @p (nearest player), and live also tries @p → @a → @e[type=player] in order, reporting each result.

• Large builds may hit the MCP host's request timeout: the build tool sends each fill one by one and waits for the game's response; in practice, a hollow sphere of radius 6 (126 commands) takes about 13 seconds, but longer when the game is busy. MCP clients default to a 60-second timeout; exceeding it causes the request to be cut off at the host (the tool itself keeps running). Use mc_build_preview to check fillBatches first, and build in batches when the count is large.

• Each BlockHand process still holds its own listening port: when the STDIO client closes, the server closes the Minecraft WebSocket and releases the port in sync. When the AI tool's desktop version loads multiple tasks at once, or when desktop/CLI/IDE run in parallel, the first instance gets the preferred port and the rest automatically get free ports; always use the current task's mc_status.connectCommand to have the game connect to the instance you actually want to operate. If you need a fixed port, assign different MINECRAFT_EDU_WS_PORT values to each client, or set MINECRAFT_EDU_WS_PORT_FALLBACK to 0.

• The first command after the handshake used to always time out; now fixed: reproduced in four independent real-device runs—the game sends an encrypted frame before the server has its decryptor in place, and the stream misalignment makes the next request's response unreadable. AES-CFB8 self-synchronizes, so only the first command is affected. The adapter now automatically sends a read-only time query daytime after the handshake to absorb that loss and discards the result, so the caller's first action works normally. stderr logs primed post-handshake stream.

• Events fire only when they actually happen: BlockPlaced fires only when a player places a block by hand; neither /setblock nor /fill counts. To receive events, you must subscribe first, then make the event actually happen.

• Some responses have requestIds that don't match the request (IDs of all zeros have been observed). When only one pending request remains, the adapter attributes the response to it and logs in stderr that this was inferred; otherwise those requests time out silently, and the caller only sees "no response" rather than the real failure reason.

• Only one game connection is maintained at a time; a new connection replaces the old one.

• Environment verified on real hardware: Minecraft Education 1.26.32.0 (Win32 desktop). If you switch to the Microsoft Store UWP version, loopback is blocked by Windows app isolation and requires an additional CheckNetIsolation LoopbackExempt exemption. See agents/docs/macos-support.md for the macOS 14+ acceptance matrix.

9. License

This project is released under the MIT License. You are free to use, modify, distribute, and sublicense it, including for commercial purposes, with the sole condition that the original copyright notice and license terms be retained.

The software is provided "as is", without any express or implied warranty.

Minecraft and Minecraft Education are trademarks of Mojang Studios and Microsoft; this project is not affiliated with or endorsed by either.