# 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)