BlockHand
BlockHand is an MCP server that lets an AI client control and observe Minecraft Education Edition through the game's built-in /connect WebSocket.
Manage the bridge: check or await the game connection, inspect status, and run single or batched raw slash commands.
Drive the Education Agent robot: summon, move, turn, teleport, attack/destroy/till, place blocks, collect items, inspect inventory, sense blocks/redstone, and run multi-step action programs.
Edit the world: set/fill/clone blocks, query entities, summon mobs, change time/weather/gamerules/difficulty, save/load structures, create ticking areas, teleport, give items, switch gamemode, apply effects, and perform player actions.
Build efficiently: preview and build geometric shapes or arbitrary coordinate-to-block blueprints, with automatic fill merging and batching.
Read and verify: test/read blocks, verify block-reading parsing, compare equal-sized regions, and analyze mirror symmetry with asymmetric-cell reporting.
Interact with players: send chat/tell/title/actionbar messages and play sounds/particles.
Observe events: list, subscribe, unsubscribe, and poll game events using a cursor-based ring buffer.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BlockHand build a hollow glass sphere with radius 5 in front of me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildNode 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).PathBelow, <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 removesubcommands, 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:
Client | Written to | Afterwards |
Codex |
| Fully quit and restart; shared by desktop/CLI/IDE |
Claude Code |
| Reopen the session |
Gemini CLI |
| Restart the CLI |
Grok CLI |
| Restart the CLI |
Read strategies differ: Codex and Grok have
mcp list --json, so machine-readable output is used directly. Claude Code and Gemini'slistonly 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.jsThree 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 userfor global availability.Claude's default scope is local (only effective in the current directory);
--scope projectwrites 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 likeC:\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 LoopbackExemptexemption (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 doctorIt 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 listOr 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 connectThis 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.
In the current AI conversation, call
mc_statusand copy theconnectCommandit returns.Open Minecraft Education and enter a world (staying on the main menu does nothing).
The world must have Cheats enabled, and the operator needs Admin/OP permissions.
Type manually in the chat bar, for example:
/connect 127.0.0.1:19131You'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: mc-mcp-server
2. Real-Device Verification
First, run the safe diagnostics that don't require launching the game:
corepack pnpm run doctor
# 機器可讀版本
corepack pnpm blockhand doctor --jsondoctor 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 liveThe 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 andmc_read_blockresults are trustworthy.false→ the protocol has drifted. In this casemc_read_blockalways returns an error rather thannull(see Section 3), so no one can mistake "can't read" for "it's empty there." The returnedrawis the game's original message; compare it againstPATTERNSinsrc/domain/block-report.tsto see which pattern needs to be added.
Three signals that make you want to run it:
mc_read_blockstarts returning errors, but you can see in the game that the cell clearly has something in it.The game just updated, and you're about to do anything that depends on reading (grading, symmetry analysis).
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 --keepVerification 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 verify3. Tool Surface
Connection and Fallback (4)
Tool | Purpose |
| Bridge status, connection command, subscribed events, cumulative command count. Check this first on any failure |
| Block until the game connects (single wait up to 120 seconds) |
| Single-line raw slash command; fallback when no dedicated tool exists |
| Execute multiple raw commands in sequence |
Agent — Hands and Feet (10)
Tool | Purpose |
| Summon an Agent |
| Walk N cells in a given direction |
| Turn left/right, 90 degrees each time |
| Call a lost Agent back to the player's side |
| attack/destroy/till, can be chained |
| Place a block from an inventory slot |
| Pick up dropped items |
| count/space/detail/drop/dropAll/transfer |
| inspect/inspectData/detect/detectRedstone — the Agent's eyes |
| Send an entire action program at once, reporting results step by step |
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_blockis a yes/no question: you have to guess a block ID first.mc_read_blockdoesn'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 intomc_set_block. When parsing fails, this tool returns an error, not a successful response withnull— the reason is below.mc_verify_readingproactively verifies that the parsing path above still works. Run it once before class to know whethermc_read_blockresults can be trusted.mc_compare_regionscompares an entire region with a singletestforblocks. Per-cell comparison hits host timeouts beyond a few hundred cells; this one doesn't.maskedmode 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:
Mode | When to use | Lifecycle |
| When the AI is modifying a building and wants a fallback — save a version, load it back if the edit goes wrong | Disappears when the game closes; nothing on disk |
| When the user explicitly asks to keep it ("help me remember this building") | Written to the world folder; survives game close |
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:
Save the analysis region — abort on failure (usually an unloaded chunk).
Back up the scratch region first — abort on backup failure, and never place the mirrored copy, leaving the world untouched.
Place the mirrored copy and compare.
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)
Tool | Purpose |
| Compute only, don't build: block count, bounding box, fill batch count |
| line/box/sphere/ellipsoid/cylinder/cone/pyramid/disk/torus/helix/curve/revolution, most support hollow |
| Preview for per-cell blueprints |
| Arbitrary shapes: give a "coordinate → block" list, identical blocks auto-merged |
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_structurewithsaveMode="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 ismemory(temporary, gone when the game closes);diskshould 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
/connectin, 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:
Only single lines are allowed — newlines and NUL are rejected outright;
\ncan't split one request into two commands.wsserverandconnectare rejected — they would point the game at a different endpoint, breaking all tools afterward.Other commands are tagged with
read-only/world-write/wide-effectrisk 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_actionnatively accepts@aandkillis 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.
Path | Behavior |
Raw commands | Directly reject |
|
|
Building and world settings | Completely unaffected ( |
"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.
Variable | Default | Description |
|
| Listening address; by default binds only to loopback |
|
| Preferred listening port; the actual value is what |
|
| When the preferred port is taken by another MCP task, the OS automatically assigns a free port; set to |
|
| Timeout for a single command waiting for the game's response |
|
| Interval for sending keepalive probes ( |
|
| Number of entries in the event ring buffer |
|
| Maximum number of blocks per build operation; rejected if exceeded |
|
| Classroom guard: actions affecting players must name them explicitly; raw commands reject kill/kick/op/deop/clear/ability. Set |
|
| Default interval between steps of an Agent program |
| unset | Setting it to |
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, includingfill/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
agentsubcommands are not officially documented by Mojang; they come from public observation, and game updates may change behavior.mc_events_subscribeallows names outside the list but marks them as unverified.The argument order of
agent setitemis unconfirmed; no dedicated tool has been made for it yet. When needed, usemc_run_command.@smay not resolve under WebSocket commands: commands sent through the bridge have no entity identity, and in practicequerytarget @sreturns no response at all.mc_query_targettherefore defaults to@p(nearest player), andlivealso 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
fillone 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). Usemc_build_previewto checkfillBatchesfirst, 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.connectCommandto have the game connect to the instance you actually want to operate. If you need a fixed port, assign differentMINECRAFT_EDU_WS_PORTvalues to each client, or setMINECRAFT_EDU_WS_PORT_FALLBACKto0.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 daytimeafter the handshake to absorb that loss and discards the result, so the caller's first action works normally. stderr logsprimed post-handshake stream.Events fire only when they actually happen:
BlockPlacedfires only when a player places a block by hand; neither/setblocknor/fillcounts. 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 LoopbackExemptexemption. Seeagents/docs/macos-support.mdfor 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.
Available Tools
42 toolsmc_agent_actAgent 攻擊/挖掘/耕地ADestructive
對指定方向做動作:attack 攻擊生物、destroy 挖掉方塊並收進背包、till 把泥土翻成耕地。repeat 可連續執行。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: action (required), repeat, delayMs, direction. Returns: ok, failed, issued, outcomes, +3 more
mc_agent_collectAgent 撿取掉落物A
撿取 Agent 附近的掉落物。item 留空代表全部撿。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: item. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_agent_create召喚 AgentAIdempotent
在玩家旁邊生成 Agent。已存在時重複呼叫是安全的。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: no named parameters. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_agent_inventoryAgent 背包操作A
對 Agent 背包做一件事:count 查槽內數量、space 查剩餘空間、detail 查物品細節、drop 丟出指定數量、dropAll 清空整槽方向、transfer 在槽之間搬移。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: action (required), slot, quantity, direction, +1 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_agent_moveAgent 移動A
讓 Agent 往指定方向走 steps 格,每格一條指令。被方塊擋住時該步會失敗但不會中斷後續。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: direction (required), steps, delayMs. Returns: ok, failed, issued, outcomes, +3 more
mc_agent_placeAgent 放置方塊A
從指定背包槽(1–27)取出方塊放到指定方向。槽位空的時候會失敗。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: slot (required), repeat, delayMs, direction. Returns: ok, failed, issued, outcomes, +3 more
mc_agent_program執行一段 Agent 程式ADestructive
把一連串 Agent 動作當成一支程式依序執行,這是讓 Agent 真正「做事」的主力工具:邊走邊鋪路、挖一條隧道、耕一整片田都用它。每步結果都會個別回報,可設定失敗即停。
Inputs: steps (required), delayMs, stopOnError. Returns: ok, failed, issued, commands, +4 more
mc_agent_senseAgent 感測周遭ARead-onlyIdempotent
讀取 Agent 周圍狀態,不改變世界:inspect 看方塊種類、inspectData 看方塊資料值、detect 偵測該方向是否有實體方塊、detectRedstone 偵測紅石訊號。這是 Agent 的「眼睛」,行動前先看。
Inputs: mode, direction. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_agent_teleportAgent 傳送到玩家身邊AIdempotent
把 Agent 叫到玩家旁邊。Agent 走丟、卡住或掉進洞裡時用這個回收。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: no named parameters. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_agent_turnAgent 轉向A
讓 Agent 原地左轉或右轉,每次 90 度。times=2 等於轉身。Agent 是 Education Edition 專屬的機器人,必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向,不是世界方位。
Inputs: direction (required), times. Returns: ok, failed, issued, outcomes, +3 more
mc_analyze_symmetry分析建築的鏡像對稱程度ADestructiveIdempotent
檢查一塊區域是否左右(或前後)對稱,並在不對稱時指出哪幾塊不對稱。批改學生作品用這個:分數是對稱格子的比例,不是憑感覺。原理:testforblocks 只會平移比對不會鏡像,所以先用 structure save/load 的 mirror 參數做出鏡像副本,再跟原區比對。⚠️ 這會暫時寫入 scratch 指定的暫存區:流程一定先備份該區內容,比對完立刻還原;備份失敗就中止且不動世界。scratch 不可與分析區重疊,否則鏡像副本會蓋掉原始建築。區域受 structure 指令上限限制(64×384×64)。
Inputs: to (required), from (required), scratch (required), mirror, +1 more. Returns: score, mirror, symmetric, totalCells, +4 more
mc_await_connection等待 Minecraft 連入ARead-only
阻塞等待遊戲連上橋接,最多等 timeoutSeconds 秒。逾時不算錯誤,只是回報 connected=false。適合在請使用者輸入 /connect 之後呼叫。
Inputs: timeoutSeconds. Returns: host, port, connected, encrypted, +8 more
mc_blueprint_preview預覽藍圖建造ARead-onlyIdempotent
只計算不動工:把一份逐格藍圖依方塊種類分組,回報總方塊數與合併後的 fill 批次數。
Inputs: entries (required). Returns: block, shape, bounds, blockCount, +3 more
mc_build_blueprint建造逐格藍圖ADestructiveIdempotent
蓋出任意形狀:直接給一份「座標 → 方塊」清單,相同方塊會自動合併成最少的 fill。幾何形狀請優先用 mc_build_shape;這個工具是給像素畫、文字、不規則造型或從外部資料轉來的模型用的。
Inputs: entries (required). Returns: ok, plan, failed, issued, +4 more
mc_build_preview預覽幾何建造ARead-onlyIdempotent
只計算不動工:回報這個形狀會用掉幾個方塊、邊界盒在哪、會拆成幾條 fill 指令。座標一律是絕對世界座標;不知道玩家在哪就先用 mc_query_target。建造會直接改變世界,動手前建議先用對應的 preview 工具看方塊數與邊界盒。
Inputs: block (required), shape (required), blockStates. Returns: block, shape, bounds, blockCount, +3 more
mc_build_shape建造幾何形狀ADestructiveIdempotent
直接在世界蓋出形狀:line 線、box 方體、sphere 球、ellipsoid 橢球、cylinder 圓柱、cone 圓錐、pyramid 金字塔、disk 圓盤/圓環、torus 甜甜圈、helix 螺旋。多數形狀有 hollow 可只蓋外殼。方塊座標會自動合併成最少的 fill 指令,所以蓋一顆半徑 20 的球只要幾百條指令而不是三萬條。座標一律是絕對世界座標;不知道玩家在哪就先用 mc_query_target。建造會直接改變世界,動手前建議先用對應的 preview 工具看方塊數與邊界盒。
Inputs: block (required), shape (required), blockStates. Returns: ok, plan, failed, issued, +4 more
mc_clone複製一塊區域ADestructive
把 begin–end 的區域複製到 destination。cloneMode="move" 會把原地清空。適合把手工蓋好的樣板量產。
Inputs: end (required), begin (required), destination (required), maskMode, +1 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_compare_regions比對兩個等大區域是否一致ARead-onlyIdempotent
用一條指令比對整片區域,適合檢查學生蓋的東西跟參考範例是否相同。逐格比對在幾百格以上就會撞到 MCP host 逾時,這個不會。masked=true 會忽略來源區域裡的空氣,只檢查「該有的東西在不在」,不管周圍多了什麼;masked=false 則要求完全一致。兩個區域大小必須相同,destination 是目標區域的最小角。
Inputs: end (required), begin (required), destination (required), masked. Returns: ok, data, elapsedMs, identical, +3 more
mc_effect施加或清除狀態效果C
action="apply" 施加藥水效果,"clear" 清除全部效果。
Inputs: action, effect, target, seconds, +2 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_events_catalog列出可訂閱的事件名稱ARead-onlyIdempotent
回傳已知可用的事件名稱。Mojang 沒有正式文件化這份清單,所以訂閱清單外的名稱是允許的,只會被標記為未驗證。無副作用。
Inputs: no named parameters. Returns: eventNames
mc_events_poll讀取已收到的事件ARead-only
取出游標之後的事件。第一次用 afterCursor=0,之後帶回上次回傳的 nextCursor 就能連續讀。dropped 大於 0 代表緩衝環繞、有事件永遠讀不到了,該提高輪詢頻率。無副作用。
Inputs: limit, eventName, afterCursor. Returns: events, dropped, nextCursor
mc_events_subscribe訂閱遊戲事件AIdempotent
開始接收某類遊戲事件(例如 PlayerMessage 聊天、BlockPlaced 放置方塊、PlayerTravelled 移動)。事件會存進環形緩衝,之後用 mc_events_poll 取出。這是讓 AI「感知」玩家在做什麼的方式。重新連線後會自動重新訂閱。
Inputs: eventName (required). Returns: verified, eventName, subscribedEvents
mc_events_unsubscribe取消訂閱遊戲事件AIdempotent
停止接收某類事件。已經收進緩衝的事件不會被清除。
Inputs: eventName (required). Returns: eventName, subscribedEvents
mc_feedback播放音效或粒子B
播一個音效或在座標生成粒子效果,用來給玩家即時的感官回饋。
Inputs: id (required), kind (required), target, position. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_fill填滿一個長方體ADestructiveIdempotent
用同一種方塊填滿 from 到 to 的長方體。Bedrock 單次上限 32768 格;超過請改用 mc_build_shape,它會自動拆批。mode=hollow 只留外殼、outline 只留邊框。
Inputs: to (required), from (required), block (required), mode, +3 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_gamemode切換遊戲模式CIdempotent
把對象切成 survival、creative、adventure 或 spectator。
Inputs: mode (required), target. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_give給予物品B
給對象指定數量的物品。要讓 Agent 有東西可放,先 give 給玩家再交給 Agent。
Inputs: item (required), data, amount, target. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_message在遊戲內顯示訊息A
say 全體聊天、tell 私訊、title/subtitle/actionbar 在畫面上顯示大字。教學或回報進度時用這個跟玩家說話。
Inputs: message (required), target, channel. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_player_action玩家雜項動作BDestructive
kill 殺死對象、clear 清空背包(可指定單一物品)、xp 給經驗、ability 開關 worldbuilder/mayfly/mute 權限。
Inputs: action (required), item, unit, amount, +3 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_query_target查詢實體位置與朝向ARead-onlyIdempotent
用選擇器查詢實體的座標、朝向與唯一 ID,回傳已解析的 JSON。這是取得玩家或 Agent 目前位置的正規做法——建造前先問這個,才知道要蓋在哪裡。預設用 @p(最近的玩家)而非 @s:WebSocket 送進來的指令沒有實體身分,@s 在部分情況下無法解析。
Inputs: target. Returns: ok, data, details, elapsedMs, +3 more
mc_read_block讀取某座標實際是什麼方塊ARead-onlyIdempotent
回報該座標實際上放著什麼,不需要你先猜。Education 沒有讀取方塊的指令,這裡是拿空氣當哨兵去 testforblock,猜錯時遊戲的訊息會把實際方塊講出來。注意:回傳的是在地化顯示名稱(例如「泥土」)而不是方塊 ID(dirt),不能直接餵回 mc_set_block;要用 ID 判斷請改用 mc_test_block。訊息格式沒有官方保證,解析不出來時 block 會是 null 並附上原始訊息,不會亂猜。
Inputs: position (required). Returns: ok, raw, data, block, +5 more
mc_run_command執行單一 slash 指令ADestructive
送出一條原始 slash 指令,涵蓋本 server 沒有專用工具的功能。只接受單行、不得換行串接,並拒絕 wsserver/connect(那會切斷本橋接)。前導斜線可有可無。
Inputs: command (required). Returns: ok, data, risk, elapsedMs, +3 more
mc_run_commands依序執行多條 slash 指令ADestructive
照順序送出多條原始指令,每條都各自通過政策檢查。適合手動編排的巨集;大量方塊請改用 mc_build_shape 或 mc_build_blueprint,它們會自動合併成最少的 fill。
Inputs: commands (required), delayMs, stopOnError. Returns: ok, failed, issued, outcomes, +3 more
mc_set_block放置單一方塊ADestructiveIdempotent
在指定座標放一個方塊。大量方塊請改用 mc_fill 或 mc_build_shape——逐格呼叫這個工具會非常慢。
Inputs: block (required), position (required), handling, blockStates. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_status讀取橋接與連線狀態ARead-onlyIdempotent
回報 WebSocket 橋接是否在監聽、Minecraft 是否已連入、遊戲內應輸入的 /connect 指令、已訂閱事件與累計指令數。任何工具失敗時先查這個。無副作用。
Inputs: no named parameters. Returns: host, port, connected, encrypted, +8 more
mc_structure儲存或載入結構ADestructive
把一塊區域存成具名結構,或把已存的結構放回世界。這是把 AI 蓋好的東西保存、量產、帶到別的世界的官方途徑。
saveMode 要照使用者的意圖選,不要一律用同一個:
memory(預設)=這次連線內的暫存。AI 反覆修改同一棟建築時用這個:想留退路就存一版,改壞了 load 回來。關掉遊戲就消失,不會在硬碟累積檔案。disk=使用者明確表示要保留時才用(「幫我記住這棟」「存起來下次還要用」)。它會寫成檔案存進遊戲的世界資料夾,關掉遊戲也還在——但那是真的在使用者硬碟上留東西,不要在他沒說要保留時擅自寫入。
版本管理就是取名字:castle_v1、castle_v2。同名會直接覆蓋,改版本前先換名字。遊戲沒有「列出已存結構」的指令,所以存過什麼只能靠名字記——本次連線存過的名單可以問 mc_status。
Inputs: name (required), action (required), to, from, +3 more. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_summon生成生物或實體A
在指定座標生成一個實體,可加名牌。position 留空則生在指令發起者位置。
Inputs: entity (required), nameTag, position. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_teleport傳送玩家或實體BIdempotent
把選擇器指定的對象傳送到座標。target 預設 @s 是執行指令的玩家。
Inputs: destination (required), target. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_test_block檢查某座標是不是指定方塊ARead-onlyIdempotent
不改變世界,只回報該座標是否為指定方塊。建造前確認地形、或驗證剛才蓋的東西時用。
Inputs: block (required), position (required), blockStates. Returns: ok, data, matches, elapsedMs, +3 more
mc_ticking_area新增常載區域AIdempotent
把一塊區域設為常載,讓玩家離開後那裡的機制仍會運作。Agent 要在遠處自動工作時需要這個。
Inputs: to (required), from (required), name. Returns: ok, data, elapsedMs, statusCode, +2 more
mc_verify_reading驗證「讀方塊」這條路還有效ARead-onlyIdempotent
讀方塊靠的是 testforblock 失敗訊息會洩漏方塊名稱,而那個訊息格式沒有官方穩定性保證。遊戲改版改了文案、或遊戲語言不是繁中/簡中/英文,解析就會失效——而且失效的樣子是安靜的。這支探測會主動驗證解析路徑是否仍然有效,上課前跑一次就知道 mc_read_block 的結果能不能信。它不需要事先知道那格是什麼:若該格是空氣,就拿基岩去問(保證不符)逼出失敗訊息;若該格有東西,第一問就已經給了訊息。最多兩條指令,完全不寫入世界。parseable=false 代表協定已漂移,此時 mc_read_block 的結果一律不可信。
Inputs: position (required). Returns: raw, branch, parseable, parsedName, +1 more
mc_world_settings調整世界設定AIdempotent
一次改一項世界設定:time 設定時間(day/night/noon/midnight 或 tick 數)、weather 天氣、gamerule 遊戲規則、difficulty 難度。
Inputs: value (required), setting (required), rule, durationSeconds. Returns: ok, data, elapsedMs, statusCode, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
每个工具都有明确且独特的用途,例如mc_agent_*系列管理Agent行为,mc_build_*系列处理建造,mc_events_*系列订阅事件。即使有类似工具(如mc_set_block与mc_fill、mc_run_command与mc_run_commands),也在描述中明确区分了使用场景,没有模糊边界。
所有工具均以mc_前缀开头,使用小写下划线命名,且按功能领域分组(如mc_agent_、mc_build_、mc_events_),模式高度一致。动词与名词的组合虽然不完全统一,但整体规律清晰,易于预测。
工具数量为42个,但对Minecraft这样一个功能丰富的游戏来说,覆盖了Agent操作、建筑、世界管理、事件订阅等多个方面,每个工具都有存在的必要,没有冗余或缺失,规模与服务器目的匹配。
工具集涵盖了建造、查询、修改、事件处理、世界设置等完整生命周期,包括创建、读取、更新、删除的基本操作,也提供了预览和验证工具来避免错误。没有明显的功能死角,代理可以独立完成从规划到执行的完整流程。
Maintenance
Related MCP Connectors
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Manage NodePal Minecraft servers, worlds, mods, backups and console from AI agents.
All 20 YourAITools agent APIs in one MCP server. Most tools free; pay with credits or x402.
Minecraft builds and skins made by your AI agent, live in your browser tab. Export .schem.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables LLMs to control a Minecraft bot through the Mineflayer API, allowing for tasks like building, mining, and inventory management via natural language. It supports complex interactions including coordinate-based movement, block manipulation, and real-time game chat.531Apache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables AI-driven interactions with Minecraft through a WebSocket-based server and MCP protocol, allowing external MCP clients and in-game chat to trigger AI tools.4MIT
- AlicenseAqualityCmaintenanceEnables AI agents to control a Minecraft bot inside a Java Edition world via MCP, providing tools for movement, building, mining, combat, farming, trading, inventory, and world perception.551MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control Minecraft characters and build structures from blueprint files via MCP, with tools for listing, parsing, building, and verifying schematics.66 npmApache 2.0