# BlockHand (npm · @gjlmotea/blockhand-mcp)

Minecraft Education Edition MCP server: Agent robot, 24 build shapes, events. No add-on needed.

- Trust score: 82/100 (high trust)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-05

## Components

- npm · `@gjlmotea/blockhand-mcp`: 82/100 (this document), [markdown](https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp.md), [page](https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp)

## Channel facts

- Registry: `npm`
- Package: `@gjlmotea/blockhand-mcp`
- Version: `0.1.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-05.

- **Supply Chain Security**: 81/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known high-severity CVE affects zod 3.25.76, a direct dependency. A fixed version is available.
  - No install/post-install scripts declared.
  - 30 of 94 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to gjlmotea/blockhand-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 16 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 76/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 6018 tokens (~130/item across 46 items; 44 tools + 2 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 57/100
  - Stability observed for 17 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 84/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 43% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 2 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 46 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the BlockHand MCP server?

BlockHand runs locally as an npm package, launched with npx -y @gjlmotea/blockhand-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add gjlmotea-blockhand-for-minecraft-education-mcp -- npx -y @gjlmotea/blockhand-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "gjlmotea-blockhand-for-minecraft-education-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gjlmotea/blockhand-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "gjlmotea-blockhand-for-minecraft-education-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gjlmotea/blockhand-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add gjlmotea-blockhand-for-minecraft-education-mcp -- npx -y @gjlmotea/blockhand-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gjlmotea-blockhand-for-minecraft-education-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@gjlmotea/blockhand-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add gjlmotea-blockhand-for-minecraft-education-mcp --command npx --arg -y --arg @gjlmotea/blockhand-mcp
```

### Hermes

```yaml
mcp_servers:
  gjlmotea-blockhand-for-minecraft-education-mcp:
    command: "npx"
    args: ["-y", "@gjlmotea/blockhand-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "gjlmotea-blockhand-for-minecraft-education-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@gjlmotea/blockhand-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add gjlmotea-blockhand-for-minecraft-education-mcp -t stdio -c npx -a -y @gjlmotea/blockhand-mcp
```

### Other

```json
{
  "mcpServers": {
    "gjlmotea-blockhand-for-minecraft-education-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gjlmotea/blockhand-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-04 (score 82, +1)

No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-02 (score 81, +1)

No change was recorded against any check on this day. Stability & Change Management went from 43 to 47. That category is still filling its 30-day observation window: 13 days of observed history at the previous scan, 14 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-31 (score 80, +1)

No change was recorded against any check on this day. Stability & Change Management went from 37 to 40. That category is still filling its 30-day observation window: 11 days of observed history at the previous scan, 12 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-29 (score 79, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-27 (score 78, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-25 (score 77, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-24 (score 76, −5)

- [security regression] CVE-2023-54404 affects this package: high
- [security regression] Known CVEs: pass → fail

### 2026-10-22 (score 81, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

## MCP tools (44)

### `mc_undo_control` (~177 tokens)

View or configure one-step undo

Note: automatic Undo is off by default. On Education 1.26.x, once it is on, the native check before the first build makes the game command channel stop responding for good (the player's typing gets no response either) until Minecraft is restarted; configure enabled=true only when the user explicitly asks for it. action=status only reads the automatic Undo state and timings; configure turns it on or off and sets the block budget (default 4096, max 32768); same-material ranges are saved as whole regions and compared with native region checks. clear releases this server's backups. Backups live only in game memory, with no disk backup and no Redo. Turning automatic backup off clears the old history.

Input parameters:

- `action` (string)
- `enabled` (boolean)
- `maxBlocks` (integer)

Output parameters:

- `available` (boolean)
- `backupMs` (number)
- `busy` (boolean)
- `checkMs` (number)
- `enabled` (boolean)
- `maxBlocks` (integer)
- `maxRegions` (integer)
- `operationId` (string|null)
- `reason` (string|null)
- `restoreMs` (number)
- `restoredRegions` (integer)
- `snapshotCount` (integer)
- `state` (string)
- `storedBlocks` (integer)

### `mc_undo` (~154 tokens)

Undo the last build

Undo the last protected setblock/fill or build tool call; several build commands count as one step. All target blocks are checked first, then each region is restored with conditional commands so later changes are not overwritten. operationId guards against undoing the wrong version. Use overwriteChanges only when the user explicitly asks to overwrite conflicts, or accepts restoring the site after an operation whose outcome is uncertain; never set it to true on your own. This first version covers basic Overworld building blocks only: no mobs, inventories, water flow or redstone chains outside the region, and no Redo. Do not switch worlds or dimensions while it runs.

Input parameters:

- `operationId` (string)
- `overwriteChanges` (boolean)

Output parameters:

- `available` (boolean)
- `backupMs` (number)
- `busy` (boolean)
- `checkMs` (number)
- `enabled` (boolean)
- `maxBlocks` (integer)
- `maxRegions` (integer)
- `operationId` (string|null)
- `reason` (string|null)
- `restoreMs` (number)
- `restoredRegions` (integer)
- `snapshotCount` (integer)
- `state` (string)
- `storedBlocks` (integer)

### `mc_status` (~72 tokens)

Read bridge and connection status

Report the WebSocket bridge, whether the game is answering commands (commandState), the last reply and timeout times, the /connect command and subscribed events. connected only means the network link is up; timed-out means a recent command got no reply, so do not assume the game can still act. No side effects.

Output parameters:

- `bufferedEvents` (number)
- `commandState` (string)
- `commandsIssued` (number)
- `connectCommand` (string)
- `connected` (boolean)
- `connectedAt` (string|null)
- `connectionCount` (number)
- `encrypted` (boolean)
- `host` (string)
- `inFlightCommands` (number): Commands sent to the game and still waiting for a reply; the bridge sends one at a time
- `lastCommandResponseAt` (string|null)
- `lastCommandTimeoutAt` (string|null)
- `listening` (boolean)
- `port` (number)
- `queuedCommands` (number): Commands queued and not yet sent; greater than 0 means the backlog comes from concurrent calls on the client side, not from the game
- `savedStructures` (array): Structures saved during this connection; the game has no command to list structures, so the bridge keeps its own record
- `subscribedEvents` (array)
- `undo` (object)

### `mc_await_connection` (~58 tokens)

Wait for Minecraft to connect

Block until the game connects to the bridge, for at most timeoutSeconds seconds. A timeout is not an error; it just reports connected=false. Call it after asking the user to type /connect.

Input parameters:

- `timeoutSeconds` (integer)

Output parameters:

- `bufferedEvents` (number)
- `commandState` (string)
- `commandsIssued` (number)
- `connectCommand` (string)
- `connected` (boolean)
- `connectedAt` (string|null)
- `connectionCount` (number)
- `encrypted` (boolean)
- `host` (string)
- `inFlightCommands` (number): Commands sent to the game and still waiting for a reply; the bridge sends one at a time
- `lastCommandResponseAt` (string|null)
- `lastCommandTimeoutAt` (string|null)
- `listening` (boolean)
- `port` (number)
- `queuedCommands` (number): Commands queued and not yet sent; greater than 0 means the backlog comes from concurrent calls on the client side, not from the game
- `savedStructures` (array): Structures saved during this connection; the game has no command to list structures, so the bridge keeps its own record
- `subscribedEvents` (array)
- `undo` (object)

### `mc_run_command` (~84 tokens)

Run one slash command

Send one raw slash command, for anything this server has no dedicated tool for. Single line only, no newline chaining. Refuses wsserver / connect / closewebsocket, including when wrapped in execute (that would cut this bridge). The leading slash is optional.

Input parameters:

- `command` (string, required): For example "time set day" or "/give @s diamond 1"

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `risk` (string)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_run_commands` (~157 tokens)

Run several slash commands in order

Send several raw commands in order; each one passes the command policy on its own. Good for hand-written macros; for many blocks use mc_build_shape or mc_build_blueprint, which merge them into the fewest fill commands automatically.

Input parameters:

- `commands` (array, required)
- `delayMs` (integer)
- `reportFailuresOnly` (boolean): Return only the failed commands and skip the successful ones. Per-command results of a large batch (for example 200 fill commands) easily run past ten thousand tokens, and most of them just say "N bl…
- `stopOnError` (boolean)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_agent_create` (~61 tokens)

Summon the Agent

Spawn the Agent next to the player. Calling it again when the Agent already exists is safe. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_agent_move` (~103 tokens)

Move the Agent

Move the Agent steps blocks in a direction, one command per block. A step blocked by a block fails without stopping the rest. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `delayMs` (integer): Delay between steps, so the game has time to finish each move
- `direction` (string, required)
- `steps` (integer)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_agent_turn` (~78 tokens)

Turn the Agent

Turn the Agent left or right in place, 90 degrees each time. times=2 turns it around. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `direction` (string, required)
- `times` (integer)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_agent_teleport` (~70 tokens)

Teleport the Agent to the player

Bring the Agent to the player. Use it to recover the Agent when it is lost, stuck or has fallen into a hole. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_agent_act` (~107 tokens)

Agent attack / destroy / till

Act in a direction: attack hits a mob, destroy breaks a block and puts it in the inventory, till turns dirt into farmland. repeat runs it several times in a row. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `action` (string, required)
- `delayMs` (integer)
- `direction` (string)
- `repeat` (integer)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_agent_place` (~98 tokens)

Agent place block

Take a block from an inventory slot (1-27) and place it in a direction. Fails when the slot is empty. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `delayMs` (integer)
- `direction` (string)
- `repeat` (integer)
- `slot` (integer, required)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_agent_collect` (~75 tokens)

Agent collect items

Pick up dropped items near the Agent. Leave item empty to pick up everything. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `item`: Block ID, for example stone or minecraft:oak_planks

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_agent_inventory` (~147 tokens)

Agent inventory

Do one thing with the Agent inventory: count reads the amount in a slot, space reads the room left, detail reads item details, drop drops a quantity, dropAll drops everything in a direction, transfer moves items between slots. The Agent is the robot found only in Education Edition; summon it with mc_agent_create first. Directions are relative to the way the Agent faces, not world directions.

Input parameters:

- `action` (string, required)
- `destinationSlot` (integer): Required for transfer
- `direction` (string): Required for drop / dropAll
- `quantity` (integer): Required for drop / transfer
- `slot` (integer): Required for count / space / detail / drop

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_agent_sense` (~82 tokens)

Agent sense surroundings

Read what is around the Agent without changing the world: inspect reads the block type, inspectData reads the block data value, detect checks whether there is a solid block in that direction, detectRedstone checks for a redstone signal. These are the Agent's eyes; look before acting.

Input parameters:

- `direction` (string)
- `mode` (string)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_agent_program` (~101 tokens)

Run an Agent program

Run a sequence of Agent actions in order as one program. This is the main tool for getting real work done with the Agent: laying a path as it walks, digging a tunnel, tilling a whole field. Each step is reported separately, and it can stop at the first failure.

Input parameters:

- `delayMs`: Delay between steps; null uses the default of 100 ms
- `steps` (array, required)
- `stopOnError` (boolean)

Output parameters:

- `commands` (array)
- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `succeeded` (number)
- `undo` (object)

### `mc_set_block` (~87 tokens)

Place one block

Place one block at a coordinate. For many blocks use mc_fill or mc_build_shape instead; calling this tool block by block is very slow.

Input parameters:

- `block` (string, required): Block ID, for example stone or minecraft:oak_planks
- `blockStates`: Optional block states, for example ["stone_type":"granite"]
- `handling`
- `position` (object, required)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_fill` (~166 tokens)

Fill a box

Fill the box from from to to with one kind of block. Bedrock allows at most 32768 blocks per fill; beyond that use mc_build_shape, which splits the work into batches automatically. mode=hollow fills the six outer faces and clears the inside to air; mode=outline replaces only the six outer faces and leaves the inside as it is.

Input parameters:

- `block` (string, required): Block ID, for example stone or minecraft:oak_planks
- `blockStates`: Optional block states, for example ["stone_type":"granite"]
- `from` (object, required)
- `mode`
- `replaceBlock`: Only used when mode="replace"
- `replaceStates`: Optional block states, for example ["stone_type":"granite"]
- `to` (object, required)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_clone` (~69 tokens)

Clone a region

Copy the region from begin to end to destination. cloneMode="move" clears the original. Good for mass-producing a hand-built template.

Input parameters:

- `begin` (object, required)
- `cloneMode`
- `destination` (object, required)
- `end` (object, required)
- `maskMode`

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_test_block` (~83 tokens)

Test whether a coordinate holds a block

Report whether a coordinate holds the given block, without changing the world. Use it to check the terrain before building or to verify what was just built.

Input parameters:

- `block` (string, required): Block ID, for example stone or minecraft:oak_planks
- `blockStates`: Optional block states, for example ["stone_type":"granite"]
- `position` (object, required)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `matches` (boolean)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_analyze_symmetry` (~286 tokens)

Analyze how mirror-symmetric a build is

Check whether a region is symmetric left to right (or front to back), and when it is not, point out **which parts** are not. Use it to grade student builds: the score is the share of symmetric cells, not a gut feeling. How it works: testforblocks only compares by translation, never mirrored, so a mirrored copy is made first with the mirror option of structure save / load and then compared with the original. Warning: this **temporarily writes** to the scratch area: its contents are always backed up first and restored right after the comparison; if the backup fails, it stops without touching the world. scratch must not overlap the analyzed region, or the mirrored copy overwrites the original build. The region is limited by the structure command (64x384x64).

Input parameters:

- `cellsPerAxis` (integer): Subdivision when the whole region is not symmetric: n parts per axis, n^3 cells, one command per cell
- `from` (object, required): One corner of the analyzed region
- `mirror` (string): Mirror axis: x checks left-right symmetry, z checks front-back symmetry, xz requires both
- `scratch` (object, required): Minimum corner of the scratch area; it is overwritten and then restored, and must not overlap the analyzed region
- `to` (object, required): The opposite corner of the analyzed region

Output parameters:

- `asymmetricCells` (array)
- `commandsIssued` (number)
- `matchedCells` (number)
- `mirror` (string)
- `score` (number): 0-100, the share of symmetric cells
- `scratchRestored` (boolean): false means the scratch area was not restored and the world was left changed
- `symmetric` (boolean)
- `totalCells` (number)

### `mc_read_block` (~149 tokens)

Read which block is at a coordinate

Report what is actually at a coordinate, without you having to guess first. Education has no command to read a block, so this runs testforblock with air as a sentinel; when the guess is wrong, the game message names the actual block. Note: it returns the **localized display name** (for example "Dirt", or "泥土" in a Chinese game), not the block ID (dirt), so it cannot be fed back to mc_set_block; to check by ID, use mc_test_block. The message format has no official guarantee; when it cannot be parsed, this tool returns an error with the raw message instead of guessing.

Input parameters:

- `position` (object, required)

Output parameters:

- `block` (string): Localized display name; when it cannot be parsed, this tool returns an error instead of null
- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `isAir` (boolean)
- `ok` (boolean)
- `raw` (string|null)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_verify_reading` (~194 tokens)

Verify that block reading still works

Block reading relies on the testforblock **failure message** revealing the block name, and that message format has no official stability guarantee. When a game update changes the wording, or the game language is not Traditional Chinese, Simplified Chinese or English, parsing breaks, and it breaks **silently**. This probe actively checks whether the reading path still works; **run it once before class** to know whether mc_read_block results can be trusted. It does not need to know what is at the spot: if it is air, it asks about bedrock (a guaranteed mismatch) to force a failure message; if something is there, the first question already produced a message. At most two commands, and it never writes to the world. parseable=false means the protocol has drifted, and mc_read_block results cannot be trusted at all.

Input parameters:

- `position` (object, required): Any coordinate works, empty or not

Output parameters:

- `branch` (string)
- `commandsIssued` (number)
- `parseable` (boolean): false means the protocol has drifted and block reading cannot be trusted
- `parsedName` (string|null)
- `raw` (string|null)

### `mc_compare_regions` (~154 tokens)

Compare two regions of equal size

Compare a whole region with one command; good for checking whether a student build matches a reference. Comparing block by block hits the MCP host timeout beyond a few hundred blocks; this does not. masked=true ignores air in the source region and only checks that what should be there is there, regardless of anything extra around it; masked=false requires an exact match. Both regions must be the same size; destination is the minimum corner of the target region.

Input parameters:

- `begin` (object, required): One corner of the source region
- `destination` (object, required): Minimum corner of the target region
- `end` (object, required): The opposite corner of the source region
- `masked` (boolean): When true, air in the source is ignored

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `identical` (boolean)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_query_target` (~118 tokens)

Query entity position and facing

Query the coordinates, facing and unique ID of entities by selector, returned as parsed JSON. This is the standard way to get the current position of the player or the Agent; ask this before building so you know where to build. It defaults to @p (the nearest player) rather than @s: commands sent over the WebSocket have no entity identity, so @s cannot be resolved in some cases.

Input parameters:

- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `details`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_summon` (~63 tokens)

Summon a mob or entity

Spawn one entity at a coordinate, optionally with a name tag. Leave position empty to spawn it where the command runs.

Input parameters:

- `entity` (string, required): Entity ID, for example cow or minecraft:villager
- `nameTag`
- `position`

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_world_settings` (~99 tokens)

Change a world setting

Change one world setting at a time: time sets the time (day/night/noon/midnight or a tick count), weather the weather, gamerule a game rule, difficulty the difficulty.

Input parameters:

- `durationSeconds`
- `rule` (string): Rule name when setting="gamerule"
- `setting` (string, required)
- `value` (string, required): time: day | weather: clear | difficulty: peaceful | the gamerule value

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_structure` (~354 tokens)

Save or load a structure

Save a region as a named structure, or place a saved structure back into the world. This is the official way to keep what the AI built, mass-produce it, or take it to another world.

\**Choose saveMode by what the user wants; do not always use the same one:**
\- `memory` (default) = temporary storage for this connection. Use it while the AI keeps revising the same build: save a version to keep a way back, and load it if a change goes wrong. It disappears when the game closes and leaves no files on disk.
\- `disk` = only when **the user explicitly says to keep it** ("remember this building", "save it so I can use it next time"). It is written as a file into the game world folder and survives closing the game, which really leaves something on the user disk, so do not write it when they did not ask to keep it.

Versioning is **naming**: `castle_v1`, `castle_v2`. The same name overwrites without warning, so change the name before saving a new version. The game has no command to list saved structures, so names are the only record; mc_status lists the ones saved during this connection.

Input parameters:

- `action` (string, required)
- `destination` (object): Required for load
- `from` (object): Required for save
- `includeEntities` (boolean)
- `name` (string, required): Versions are told apart by this; the same name overwrites
- `saveMode` (string): memory = temporary (default); disk = written to disk, only when the user explicitly says to keep it
- `to` (object): Required for save

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_ticking_area` (~54 tokens)

Add a ticking area

Keep a region loaded so its mechanisms keep running after the player leaves. Needed when the Agent works on its own far away.

Input parameters:

- `from` (object, required)
- `name`
- `to` (object, required)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_teleport` (~67 tokens)

Teleport a player or entity

Teleport the targets of a selector to a coordinate. target defaults to @s, the player running the commands.

Input parameters:

- `destination` (object, required)
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_give` (~97 tokens)

Give items

Give a target a number of items. To give the Agent something to place, give it to the player first and then hand it to the Agent.

Input parameters:

- `amount` (integer)
- `data`
- `item` (string, required): Block ID, for example stone or minecraft:oak_planks
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_gamemode` (~56 tokens)

Change game mode

Switch the target to survival, creative, adventure or spectator.

Input parameters:

- `mode` (string, required)
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_effect` (~98 tokens)

Apply or clear status effects

action="apply" applies a potion effect; "clear" removes all effects.

Input parameters:

- `action` (string)
- `amplifier` (integer)
- `effect` (string): Required for apply, for example speed or night_vision
- `hideParticles` (boolean)
- `seconds` (integer)
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_player_action` (~118 tokens)

Miscellaneous player actions

kill kills the target, clear empties the inventory (optionally one item only), xp gives experience, ability turns the worldbuilder / mayfly / mute abilities on or off.

Input parameters:

- `ability` (string)
- `action` (string, required)
- `amount` (integer): Required for xp
- `enabled` (boolean)
- `item`: Optional for clear
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name
- `unit` (string)

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_message` (~86 tokens)

Show a message in the game

say posts to everyone in chat, tell sends a private message, title / subtitle / actionbar show large text on screen. Use it to talk to players while teaching or reporting progress.

Input parameters:

- `channel` (string)
- `message` (string, required)
- `target` (string): Target selector (@a/@p/@s/@e/@r, optionally with []) or a player name

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_feedback` (~75 tokens)

Play a sound or particle

Play a sound or spawn a particle effect at a coordinate, to give players immediate sensory feedback.

Input parameters:

- `id` (string, required): Sound or particle ID, for example random.levelup or minecraft:heart_particle
- `kind` (string, required)
- `position`
- `target` (string): Who hears it when kind="sound"

Output parameters:

- `commandLine` (string)
- `data`
- `elapsedMs` (number)
- `ok` (boolean)
- `statusCode` (number|null)
- `statusMessage` (string|null)
- `undo` (object)

### `mc_build_preview` (~126 tokens)

Preview a shape build

Compute only, build nothing: report how many blocks the shape uses, where its bounding box is, and how many fill commands it splits into. All coordinates are absolute world coordinates; if you do not know where the player is, call mc_query_target first. Building changes the world directly, so check the block count and bounding box with the matching preview tool before you build.

Input parameters:

- `block` (string, required): Block ID, for example stone or minecraft:oak_planks
- `blockStates`: Optional block states, for example ["stone_type":"granite"]
- `shape` (required)

Output parameters:

- `block` (string)
- `blockCount` (number)
- `blockStates` (string|null)
- `bounds` (object)
- `fillBatches` (number)
- `savedCommands` (number)
- `shape` (string)

### `mc_build_shape` (~492 tokens)

Build a shape

Build a shape directly in the world. Block coordinates are merged into the fewest fill commands automatically, so a sphere of radius 20 takes a few hundred commands instead of thirty thousand.
[Choose a shape by intent]
Basic volumes: box, sphere, ellipsoid, cylinder, cone (topRadius>0 makes a truncated cone), pyramid (sides sets the number of sides, topRadius>0 makes a frustum), prism (regular n-sided prism).
Lines and surfaces: line (straight line), curve (smooth curve), disk (disk / ring), tube (cylinder in any direction).
Building parts: wedge (single slope), roof (gable / hip), arch, stairs (straight stairs), spiralStairs, polywall (polyline wall / city wall).
Terrain and paths: heightfield (rolling ground), ribbon (road / bridge deck).
Decoration and forms: torus (ring), helix, cross (plus-shaped column), star (star-shaped column), revolution (solid of revolution).

[Easy to confuse; read this first]
Slanted columns, beams, pipes -> tube, not cylinder (cylinder only aligns with x / y / z).
Walls or fences with right-angle turns -> polywall, not curve (curve is smooth and rounds off right angles).
A roof with a ridge -> roof; a single slope or ramp only -> wedge.
Stairs that wind around a tower -> spiralStairs; straight up and down -> stairs.
Tower bodies, bases or chimneys that are wider at one end -> cone or pyramid with topRadius, not stacked layers of box.
Domes, vases, paraboloids, cooling towers and other round forms whose width changes -> revolution with a different profile; no other shape is needed.
A stretch of rolling ground -> heightfield; a flat road with a width -> ribbon.

If unsure, check the block count and bounding box with mc_build_preview first; it does not touch the world.

All coordinates are absolute world coordinates; if you do not know where the player is, call mc_query_target first. Building changes the world directly, so check the block count and bounding box with the matching preview tool before you build.

Input parameters:

- `block` (string, required): Block ID, for example stone or minecraft:oak_planks
- `blockStates`: Optional block states, for example ["stone_type":"granite"]
- `shape` (required)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `plan` (object)
- `succeeded` (number)
- `undo` (object)

### `mc_blueprint_preview` (~46 tokens)

Preview a blueprint build

Compute only, build nothing: group a block-by-block blueprint by block type and report the total block count and the number of merged fill batches.

Input parameters:

- `entries` (array, required)

Output parameters:

- `block` (string)
- `blockCount` (number)
- `blockStates` (string|null)
- `bounds` (object)
- `fillBatches` (number)
- `savedCommands` (number)
- `shape` (string)

### `mc_build_blueprint` (~68 tokens)

Build a block-by-block blueprint

Build any form from a list of coordinate -> block entries; identical blocks are merged into the fewest fill commands automatically. Prefer mc_build_shape for geometric shapes; this tool is for pixel art, text, irregular forms, or models converted from external data.

Input parameters:

- `entries` (array, required)

Output parameters:

- `elapsedMs` (number)
- `failed` (number)
- `firstFailure`
- `issued` (number)
- `ok` (boolean)
- `outcomes` (array)
- `plan` (object)
- `succeeded` (number)
- `undo` (object)

### `mc_events_catalog` (~47 tokens)

List subscribable event names

Return the event names known to work. Mojang does not formally document this list, so subscribing to a name outside it is allowed; it is just marked unverified. No side effects.

Output parameters:

- `eventNames` (array)

### `mc_events_subscribe` (~82 tokens)

Subscribe to game events

Start receiving a kind of game event (for example PlayerMessage for chat, BlockPlaced for placed blocks, PlayerTravelled for movement). Events go into a ring buffer; read them later with mc_events_poll. This is how the AI perceives what the player is doing. Subscriptions are renewed automatically after a reconnect.

Input parameters:

- `eventName` (string, required)

Output parameters:

- `eventName` (string)
- `subscribedEvents` (array)
- `verified` (boolean)

### `mc_events_unsubscribe` (~33 tokens)

Unsubscribe from game events

Stop receiving a kind of event. Events already in the buffer are kept.

Input parameters:

- `eventName` (string, required)

Output parameters:

- `eventName` (string)
- `subscribedEvents` (array)

### `mc_events_poll` (~92 tokens)

Read received events

Return the events after a cursor. Use afterCursor=0 the first time, then pass back the nextCursor from the previous call to keep reading. dropped greater than 0 means the buffer wrapped around and some events are lost for good; poll more often. No side effects.

Input parameters:

- `afterCursor` (integer)
- `eventName`: Only return this kind of event
- `limit` (integer)

Output parameters:

- `dropped` (number)
- `events` (array)
- `nextCursor` (number)

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp#diagnostics

## Score history

- 2026-11-05: 82
- 2026-11-04: 82
- 2026-11-03: 81
- 2026-11-02: 81
- 2026-11-01: 80
- 2026-10-31: 80
- 2026-10-30: 79
- 2026-10-29: 79
- 2026-10-28: 78
- 2026-10-27: 78
- 2026-10-26: 77
- 2026-10-25: 77
- 2026-10-24: 76
- 2026-10-23: 81
- 2026-10-22: 81
- 2026-10-21: 80
- 2026-10-20: 80
- 2026-10-19: 79

## Common questions

### What is the BlockHand MCP server?

BlockHand is an MCP server listed in the public MCP registry as io.github.gjlmotea/blockhand-for-minecraft-education-mcp. Minecraft Education Edition MCP server: Agent robot, 24 build shapes, events. No add-on needed. This page covers its npm package (@gjlmotea/blockhand-mcp).

### Is the BlockHand MCP server safe to use?

BlockHand scores 82 out of 100 on VerifyMCP. We recorded 1 known advisory against it as of 5 November 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the BlockHand MCP server expose?

BlockHand exposes 44 tools: mc_undo_control, mc_undo, mc_status, mc_await_connection, mc_run_command, and 39 more. Their descriptions and schemas cost roughly 5,083 tokens of context every time the server is loaded.

### Is the BlockHand MCP server still maintained?

BlockHand is still listed as active in the MCP registry. We last reached this channel on 5 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the BlockHand MCP server under?

BlockHand declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/@gjlmotea/blockhand-mcp
- Socket report: https://socket.dev/npm/package/@gjlmotea/blockhand-mcp
- Repository: https://github.com/gjlmotea/blockhand-mcp
- Changelog RSS feed: https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp.json
- HTML version of this page: https://verifymcp.io/servers/gjlmotea-blockhand-for-minecraft-education-mcp/gjlmotea-blockhand-mcp