# Minecraft Builder MCP Server

An MCP (Model Context Protocol) server that enables Claude to generate Minecraft structures from natural language descriptions. Describe what you want to build, and Claude will create a `.schem` file that you can import into Minecraft.

## Features

- Natural language to Minecraft structure conversion
- MCP integration for Claude Desktop and Claude Code
- WorldEdit-compatible `.schem` file generation
- Automatic folder opening in Windows Explorer
- Support for structures from simple platforms to complex buildings
- No API costs - works with your Claude subscription

## Installation

### Prerequisites

- Python 3.10 or higher
- Claude Desktop or Claude Code

### Setup

1. Clone or download this repository

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Install the package:
   ```bash
   pip install -e .
   ```

4. Configure Claude Desktop or Claude Code:

   Edit your config file:
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

   Add this configuration:
   ```json
   {
     "mcpServers": {
       "minecraft-builder": {
         "command": "python",
         "args": ["-m", "minecraft_builder"]
       }
     }
   }
   ```

5. Restart Claude Desktop/Code completely

## Usage

Once installed, chat with Claude and describe structures. Claude will ask where to save the files.

### Simple Examples

```
Create a 5x5 stone platform
```

```
Build a wooden door frame using oak planks
```

```
Make a campfire area with logs arranged in a circle
```

### Complex Examples

```
Build a medieval cottage: 8x6 blocks, oak planks walls, stone foundation, glass windows, 6 blocks tall
```

```
Create a lighthouse tower with a circular stone base (7 blocks diameter), 25 blocks tall, stone for bottom 20 blocks, glass for top 5 blocks
```

```
Design a garden with a cobblestone path down the middle (10 blocks long), dirt blocks on sides for planting
```

See `examples/PROMPTS.md` for more detailed examples and tips.

### How It Works

1. You describe a structure to Claude
2. Claude generates a JSON definition with block coordinates
3. Claude asks where to save the .schem file
4. The tool converts JSON to Sponge Schematic v2 format
5. Claude can open the folder in Windows Explorer

### Tools Available

**create_minecraft_structure** - Converts structure definitions to .schem files
- Supports direct JSON input for small/medium structures
- Supports file-based input for large structures (see LARGE_STRUCTURE_GUIDE.md)

**open_folder_in_explorer** - Opens Windows Explorer at the output location
- Can highlight the created file

### Importing into Minecraft

The generated `.schem` files work with **WorldEdit**:

1. Copy the `.schem` file to your WorldEdit schematics folder:
   - Server: `[world]/plugins/WorldEdit/schematics/`
   - Client (Forge/Fabric): `.minecraft/config/worldedit/schematics/`

2. In-game commands:
   ```
   //schem load <filename>
   //paste
   ```

Alternatively, use **MCEdit**, **Amulet Editor**, or other schematic tools.

## JSON Structure Format

The tool accepts structures in this format:

```json
{
  "name": "my_structure",
  "description": "Optional description",
  "blocks": [
    {
      "x": 0,
      "y": 0,
      "z": 0,
      "block_type": "minecraft:stone"
    },
    {
      "x": 1,
      "y": 0,
      "z": 0,
      "block_type": "oak_planks"
    }
  ]
}
```

**Block IDs:**
- Full format: `minecraft:stone`, `minecraft:oak_planks`
- Short format: `stone`, `oak_planks` (auto-prefixed with `minecraft:`)

**Coordinates:**
- Origin: (0, 0, 0)
- X: Width, Y: Height, Z: Length
- All coordinates relative to structure origin

## Compatibility

- Schematic format: Sponge Schematic v2
- Minecraft version: 1.13+ (1.19.4 target)
- WorldEdit 7.x required for import

## Project Structure

```
llm-minecraft-builds/
├── src/minecraft_builder/
│   ├── __init__.py
│   ├── __main__.py       # MCP server entry point
│   ├── server.py          # MCP server and tool definitions
│   ├── schema.py          # Pydantic data models
│   └── converter.py       # JSON to .schem converter
├── examples/
│   ├── example_structures.json
│   └── PROMPTS.md
├── requirements.txt
├── pyproject.toml
├── README.md
├── CLAUDE.md              # Instructions for Claude Code
└── LARGE_STRUCTURE_GUIDE.md
```

## Troubleshooting

**MCP server not appearing:**
- Completely restart Claude Desktop
- Verify config file location and syntax
- Check Python is accessible: `python --version`
- Ensure package is installed: `pip list | grep minecraft-builder`

**Installation errors:**
- Use Python 3.10 or higher
- Install all dependencies: `pip install -r requirements.txt`
- Try: `pip install -e . --force-reinstall`

**Structure won't import in Minecraft:**
- Verify .schem file was created
- Check WorldEdit is installed (version 7.x+)
- Confirm Minecraft version is 1.13 or newer
- Use `//schem list` in-game to verify file is detected

**Large structures truncated:**
- See `LARGE_STRUCTURE_GUIDE.md` for handling complex structures
- For 300+ blocks, ask Claude to write JSON to file first

**Path issues (WSL):**
- Provide Windows paths: `C:\Users\username\Desktop`
- Avoid WSL paths: `/mnt/c/Users/...`

## Development

### Running locally

```bash
cd src
python -m minecraft_builder
```

The server runs in stdio mode for MCP communication.

### Testing

```bash
python test_converter.py
```

## Dependencies

- **mcp** (>=0.9.0) - MCP Python SDK
- **mcschematic** (>=11.0.0) - Minecraft schematic file handling
- **pydantic** (>=2.0.0) - Data validation

## Contributing

Contributions welcome:
- Additional output formats (.nbt, .litematic)
- Block state and NBT data support
- Enhanced structure validation
- More example structures

## License

MIT License

## Credits

Built using:
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) by Anthropic
- [mcschematic](https://github.com/Sloimayyy/mcschematic) for schematic file handling
- [Pydantic](https://docs.pydantic.dev/) for data validation