BlockHand — MCP server for Minecraft Education

English | 繁體中文

BlockHand gives AI agents hands and eyes inside Minecraft Education Edition. Claude Code, Codex, Gemini CLI, Grok or any other Model Context Protocol client can drive the Agent robot, build structures, read blocks, compare regions and react to game events.

It talks to the game only through Minecraft Education's built-in /connect (/wsserver) WebSocket command. There is no add-on, behavior pack, mod or Script API to install in the game, nothing is injected into the game process, and no screen reading is involved. On a school computer, the only thing to install is the AI client.

• 44 tools and 2 resources: Agent robot control, world edits, 24 build shapes, blueprints, block reading, region comparison, symmetry checks and event subscription.
• Fast building: shapes are merged into the fewest possible /fill commands (a solid sphere of radius 8 goes from 2,000+ blocks to under 200 commands).
• Local by default: the game WebSocket listens on 127.0.0.1 unless MINECRAFT_EDU_WS_HOST changes it, and no account or online service is involved.
• One fixed address: every AI session on the machine shares one background hub, so the game always connects with /connect 127.0.0.1:19131.
• Installers for Claude Code, Codex, Gemini CLI and Grok CLI when you run from source.

The /connect command is an official interface. The WebSocket message protocol behind it has no published stability guarantee, so behavior should be re-checked after game updates.

Contents

• Quick start
• Install from source
• Tools
• Connecting and staying connected
• How building stays fast
• Reading blocks
• Undo (off by default)
• Configuration
• Safety
• Troubleshooting
• Known limitations
• Development
• License and trademarks

Quick start

Requirements:

• Minecraft Education Edition, in a world with Cheats on. The player who connects needs operator rights. Verified on 1.26.32 (Windows desktop and macOS 14+).
• Node.js 22 or newer on the machine that runs the AI client.

1. Register the server with your AI client

Claude Code:

claude mcp add blockhand --scope user -- npx -y @gjlmotea/blockhand-mcp

Codex:

codex mcp add blockhand -- npx -y @gjlmotea/blockhand-mcp

Clients that read an mcpServers JSON config (Claude Desktop, Cursor, Gemini CLI):

{
  "mcpServers": {
    "blockhand": {
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}

VS Code uses a top-level servers key instead, and each server has a type:

{
  "servers": {
    "blockhand": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}

Where each client keeps the file:

| Client | Config file | |---|---| | Claude Desktop | macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json. Settings → Developer → Edit Config opens it | | Cursor | ~/.cursor/mcp.json for every project, .cursor/mcp.json inside one project | | Gemini CLI | ~/.gemini/settings.json (user), .gemini/settings.json (project) | | VS Code | .vscode/mcp.json in the workspace, or the user mcp.json that the MCP: Open User Configuration command opens |

Sources: Claude Desktop, Cursor, Gemini CLI, VS Code.

Desktop apps started from Finder or the Start menu often do not see your shell's PATH. If the server fails to start with a vague "server not responding" error, replace npx with its absolute path (which npx on macOS, where npx on Windows).

Restart the AI client after registering.

2. Connect the game

The game connects to the server, not the other way round.

1. Open a world in Minecraft Education. The main menu is not enough.

2. Make sure Cheats are on.

3. Type in the chat:

   /connect 127.0.0.1:19131
   

When the connection is made, a green "✔ BlockHand connected" line appears in the chat, in the game's own language: English, Traditional Chinese or Simplified Chinese, and English for any other game language. You can also ask the AI to call mc_status, which returns the exact connectCommand.

3. Ask for something

Build a hollow glass sphere with radius 6 in front of me.

Summon the Agent, walk it five blocks forward and plant a row of wheat.

Check whether the house at 0 64 0 to 20 80 20 is mirror-symmetric and show me which blocks break the symmetry.

Install from source

Use this route to work on BlockHand itself, or to use the installers and the doctor check.

git clone https://github.com/gjlmotea/blockhand-mcp.git
cd blockhand-mcp
corepack pnpm install --frozen-lockfile
corepack pnpm run build

Register with one of the installers:

corepack pnpm run setup:claude    # or setup:codex / setup:gemini / setup:grok
corepack pnpm run doctor          # add --client=claude etc. to check another client

The installers do more than write a config entry:

• They fill in the absolute path of this machine's Node, so desktop apps that cannot read nvm, Homebrew or your shell PATH still start the server.
• Before changing any setting, they run a real MCP initialize with the exact command, arguments and environment they are about to save, and check that all 44 tools are there.
• They do nothing when the server is already registered correctly, so re-running is safe.
• When an entry with the same name exists but differs, they stop and show the difference instead of overwriting someone else's settings.
• They write only through each client's official mcp add / mcp remove command, never by editing config files directly.

Remove with corepack pnpm run uninstall:claude (or uninstall:codex, and so on). It refuses to remove entries it cannot identify as belonging to this checkout.

| Client | Writes to | Then | |---|---|---| | Codex | ~/.codex/config.toml | Quit and restart; desktop app, CLI and IDE share it | | Claude Code | ~/.claude.json (user scope) | Restart the session | | Gemini CLI | ~/.gemini/settings.json (user scope) | Restart the CLI | | Grok CLI | ~/.grok/config.toml | Restart the CLI |

To register by hand, point the client at <NODE> <REPO>/dist/index.js, where <NODE> is the absolute path from node -p "process.execPath" and <REPO> is the absolute path of the checkout. Claude Code and Gemini CLI place the command differently:

claude mcp add blockhand --scope user -- <NODE> <REPO>/dist/index.js
gemini mcp add --scope user blockhand <NODE> <REPO>/dist/index.js

Claude Code wants -- before the command. Gemini CLI takes the command right after the name (gemini mcp add [options] <name> <commandOrUrl> [args...]); a -- there would leave it without a command. Gemini only needs -- after the command, in front of server arguments that collide with its own options, and BlockHand takes no arguments. Gemini's default scope is project, so use --scope user to make it global. Claude Code's default scope is local; --scope project writes a shareable .mcp.json, which is handy for a whole class. Sources: Claude Code, Gemini CLI.

Tools

Connection and fallback (6)

| Tool | Purpose | |---|---| | mc_status | Bridge state, the /connect command, subscribed events, command counters. Check this first when anything fails | | mc_await_connection | Wait for the game to connect (up to 120 seconds per call) | | mc_run_command | One raw slash command, for anything without a dedicated tool | | mc_run_commands | Several raw commands in order | | mc_undo_control | Inspect, clear or configure single-step undo (off by default) | | mc_undo | Undo the last protected build, after checking for conflicting changes |

Agent robot (10)

| Tool | Purpose | |---|---| | mc_agent_create | Summon the Agent | | mc_agent_move | Walk N blocks in a direction | | mc_agent_turn | Turn left or right by 90 degrees | | mc_agent_teleport | Bring a lost Agent back to the player | | mc_agent_act | Attack, destroy or till, optionally repeated | | mc_agent_place | Place a block from an inventory slot | | mc_agent_collect | Pick up dropped items | | mc_agent_inventory | Count, free space, item detail, drop, drop all, transfer | | mc_agent_sense | Inspect, inspect data, detect, detect redstone: the Agent's eyes | | mc_agent_program | Send a whole sequence of actions in one call and get a result per step |

Agent directions are relative to the way the Agent is facing, not compass directions.

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 and load structures), mc_ticking_area.

mc_query_target parses the JSON that querytarget returns. It is the way to find where the player or the Agent is before building.

mc_compare_regions compares two regions with a single testforblocks. Its masked mode ignores air in the source, which is how you check that a student's build contains everything it should, whatever else is around it.

mc_analyze_symmetry checks whether a region is mirror-symmetric and, when it is not, points to the cells that differ. It works by saving the region, loading a mirrored copy into a scratch area, comparing, and restoring the scratch area afterwards. The scratch area may not overlap the region being analyzed; this is checked before any command is sent. If backing up the scratch area fails, nothing is placed.

mc_structure saves to memory by default (gone when the game closes). Use saveMode: "disk" only when the user asks to keep a structure; it writes into the world folder. The game has no command that lists saved structures, so mc_status reports the names saved during the current session.

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, action bar), mc_feedback (sounds and particles).

Building (4)

| Tool | Purpose | |---|---| | mc_build_preview | Plan only: block count, bounding box, number of /fill batches | | mc_build_shape | 24 geometric shapes; most support hollow | | mc_blueprint_preview | Preview a block-by-block blueprint | | mc_build_blueprint | Any shape from a list of "coordinate → block"; identical blocks are merged |

| Group | Shapes | |---|---| | Solids | box, sphere, ellipsoid, cylinder, cone, pyramid, prism | | Lines and surfaces | line, curve (smooth curve), disk, tube (cylinder along any direction) | | Building parts | wedge (single slope), roof (gable or hip), arch, stairs, spiralStairs, polywall (polyline wall) | | Terrain and paths | heightfield (rolling ground), ribbon (road or bridge deck) | | Decorative | torus, helix, cross, star, revolution (solid of revolution) |

With 24 shapes, the real risk is