building-structures

```

┌─────────────┐ MCP ┌─────────────┐ WebSocket ┌─────────────┐

│ Claude │◄────────────►│ VibeCraft │◄─────────────►│ Minecraft │

│ (AI Chat) │ Protocol │ MCP Server │ Bridge │ Client Mod │

└─────────────┘ └─────────────┘ └─────────────┘

│

▼

┌─────────────┐

│ Minecraft │

│ Server │

└─────────────┘

```

1. You chat with Claude asking it to build something
2. Claude sends commands to the VibeCraft MCP server
3. The server forwards commands to the Fabric client mod via WebSocket
4. The client mod executes commands in Minecraft as your player

Works with any Minecraft server — vanilla, Paper, Spigot, or modded. WorldEdit optional.

---

Prerequisites

• Python 3.10+ with [uv](https://github.com/astral-sh/uv) package manager
• Java 21 (for Minecraft 1.21.x) or Java 17 (for 1.20.x)
• jq for build script: brew install jq
• Minecraft Java Edition with a launcher like [Prism](https://prismlauncher.org/)

1. Build the Client Mod

```bash

cd client-mod

./build.sh 1.21.1 # Replace with your Minecraft version

```

Output: build/release/vibecraft-client-0.1.0-mc1.21.1.jar

2. Install with Prism Launcher

1. Create instance: Add Instance → Select Minecraft version → OK
2. Add Fabric: Edit → Version → Install Loader → Fabric → OK
3. Add Fabric API: Mods → Download mods → Search "Fabric API" → Select → OK
4. Add VibeCraft: Mods → Add file → Select vibecraft-client-*.jar
5. Launch and join a world/server

3. Enable AI Control

In Minecraft chat:

```

/vibecraft allow

```

4. Install Python Dependencies

```bash

cd mcp-server

uv sync

```

5. Configure Claude Code

Add to ~/.claude.json:

```json

{

"projects": {

"/path/to/vibecraft/agent": {

"mcpServers": {

"vibecraft": {

"type": "sse",

"url": "http://127.0.0.1:8765/sse"

}

}

}

}

}

```

6. Start MCP Server

```bash

cd mcp-server

./start-vibecraft.sh

```

7. Start Claude Code

```bash

cd agent

claude

```

You're ready! Ask Claude to build something:

> "Build me a small stone cottage"

---

See [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md) for:

• Alternative launcher instructions
• Stdio mode configuration
• Troubleshooting
• WorldEdit configuration

---

Environment Variables

| Variable | Default | Description |

|----------|---------|-------------|

| VIBECRAFT_CLIENT_HOST | 127.0.0.1 | Client mod WebSocket host |

| VIBECRAFT_CLIENT_PORT | 8766 | Client mod WebSocket port |

| VIBECRAFT_CLIENT_PATH | /vibecraft | WebSocket path |

| `VIBECRAFT_WORLDE