chore: initial commit

2026-02-15 10:50:17 +01:00
commit 055b93817a
78 changed files with 23243 additions and 0 deletions
@@ -0,0 +1,61 @@
+# minecraft-mcp
+
+MCP server that bridges Claude Code to a Minecraft bot via the Clod mod's HTTP API.
+
+## Installation
+
+```bash
+cd minecraft-mcp
+pip install -e .
+```
+
+## Register with Claude Code
+
+```bash
+claude mcp add minecraft-bridge -- python -m minecraft_mcp.server
+```
+
+Verify it's registered:
+
+```bash
+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):
+
+```bash
+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)