# BlockHand

BlockHand is an MCP server for Claude Code and Codex that connects an AI agent to Minecraft Education. It controls the Agent robot, builds shapes, and inspects blocks in the world.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: gjlmotea
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/gjlmotea/blockhand-mcp
- Updated: 2026-11-02
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/blockhand

## What it does

BlockHand passes commands between an MCP client and Minecraft Education through the game’s built-in WebSocket connection. It can control the Agent robot, edit blocks, build 24 shapes, read areas, and compare regions. It also checks symmetry and listens for game events.

Minecraft Education must have cheats enabled, and the connecting player needs operator rights. Node.js 22 or newer is required on the machine running the AI client. No game add-on is needed. The WebSocket protocol may change with game updates, so behavior needs another check after an update.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MINECRAFT_EDU_WS_PORT`, `MINECRAFT_EDU_WS_HOST` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MINECRAFT_EDU_WS_PORT=<MINECRAFT_EDU_WS_PORT> --env MINECRAFT_EDU_WS_HOST=<MINECRAFT_EDU_WS_HOST> --transport stdio blockhand -- npx -y @gjlmotea/blockhand-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add blockhand --env MINECRAFT_EDU_WS_PORT=<MINECRAFT_EDU_WS_PORT> --env MINECRAFT_EDU_WS_HOST=<MINECRAFT_EDU_WS_HOST> -- npx -y @gjlmotea/blockhand-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "blockhand": {
            "command": "npx",
            "args": [
                "-y",
                "@gjlmotea/blockhand-mcp"
            ],
            "env": {
                "MINECRAFT_EDU_WS_PORT": "<MINECRAFT_EDU_WS_PORT>",
                "MINECRAFT_EDU_WS_HOST": "<MINECRAFT_EDU_WS_HOST>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "blockhand": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@gjlmotea/blockhand-mcp"
            ],
            "env": {
                "MINECRAFT_EDU_WS_PORT": "<MINECRAFT_EDU_WS_PORT>",
                "MINECRAFT_EDU_WS_HOST": "<MINECRAFT_EDU_WS_HOST>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MINECRAFT_EDU_WS_PORT=<MINECRAFT_EDU_WS_PORT> -e MINECRAFT_EDU_WS_HOST=<MINECRAFT_EDU_WS_HOST> blockhand npx -y @gjlmotea/blockhand-mcp
```
Replace <…> with your own values

## When to use it
- build specified shapes in a game world
- direct the Agent robot and plant crops
- compare world regions and find symmetry breaks
- read blocks in a selected area

## Example prompts
- Call the Agent, move it forward five blocks, and plant a row of wheat.
- Check the house between coordinates 0 64 0 and 20 80 20 for mirror symmetry, then show the blocks that break it.

## Similar
- [Context7](https://affpapa.org/en/nevibecode/mcp/context7.md) — MCP server · 5563 installs
- [Search Google Flights](https://affpapa.org/en/nevibecode/mcp/search-google-flights.md) — MCP server · 2595 installs
- [Math-MCP](https://affpapa.org/en/nevibecode/mcp/math-mcp.md) — MCP server · 5958 installs
- [pipeworx gateway](https://affpapa.org/en/nevibecode/mcp/pipeworx-gateway.md) — MCP server · 419019 installs
- [SparkForge](https://affpapa.org/en/nevibecode/mcp/sparkforge.md) — MCP server · 219896 installs
- [OpenWebSearch](https://affpapa.org/en/nevibecode/mcp/openwebsearch.md) — MCP server · 494 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
