clod/minecraft-mcp/README.md

minecraft-mcp

MCP server that bridges Claude Code to a Minecraft bot via the Clod mod's HTTP API.

Installation

cd minecraft-mcp
pip install -e .

Register with Claude Code

claude mcp add minecraft-bridge -- python -m minecraft_mcp.server

Verify it's registered:

claude mcp list

Usage

1. Launch Minecraft with the Clod mod (HTTP server runs on port 8766)
2. Start Claude Code — the MCP server connects automatically
3. Ask Claude to interact with the bot: "check the bot status", "move to 100 64 100", etc.

Configuration

Set MINECRAFT_PORT environment variable to override the default port (8766):

claude mcp add minecraft-bridge -e MINECRAFT_PORT=9000 -- python -m minecraft_mcp.server

Available Tools

Observation

• get_bot_status — position, state, dimension
• get_blocks — 3D block array in a bounding box (max 32x32x32)
• get_block — single block type and properties
• get_nearby_entities — entities within radius (default 16, max 64)
• get_inventory — bot's inventory contents
• get_biome — biome at X/Z coordinates
• list_block_types — all block IDs, with optional filter

Actions

• move_to — pathfind to coordinates
• teleport — instant teleport
• place_block — place a single block
• place_blocks — place up to 10,000 blocks
• fill — fill a bounding box (max 32x32x32)
• break_block — destroy a block
• set_state — set bot visual state (idle/thinking/building/moving)
• look_at — aim at coordinates
• chat — send in-game chat message

Interaction

• wait_for_instruction — long-poll for player !clod commands (300s timeout)