joshbker/minecraft-builder-claude-mcp-server

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:

   pip install -r requirements.txt
   

3. Install the package:

   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:

   {
     "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:

{
  "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

cd src
python -m minecraft_builder

The server runs in stdio mode for MCP communication.

Testing

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) by Anthropic
• mcschematic for schematic file handling
• Pydantic for data validation