VibeCraft

AI-Powered Minecraft Building — Build structures through natural-language conversations with Claude.

How It Works

┌─────────────┐     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.

---

Quick Start

Prerequisites

• Python 3.10+ with 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

1. Build the Client Mod

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

Supported versions

Minecraft	Java
1.21.4	21
1.21.3	21
1.21.1	21
1.21	21
1.20.6	21
1.20.4	17
1.20.1	17

Run ./build.sh --list to see all versions.

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

cd mcp-server
uv sync

5. Configure Claude Code

Add to ~/.claude.json:

{
  "projects": {
    "/path/to/vibecraft/agent": {
      "mcpServers": {
        "vibecraft": {
          "type": "sse",
          "url": "http://127.0.0.1:8765/sse"
        }
      }
    }
  }
}

6. Start MCP Server

cd mcp-server
./start-vibecraft.sh

7. Start Claude Code

cd agent
claude

You're ready! Ask Claude to build something:

"Build me a small stone cottage"

---

Detailed Setup

See docs/SETUP_GUIDE.md for:

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

---

Configuration

Environment Variables

WorldEdit Mode

• off — Use vanilla /fill and /setblock commands only
• auto — Detect WorldEdit availability, fall back to vanilla
• force — Require WorldEdit, fail if not available

Set VIBECRAFT_WORLDEDIT_MODE=off if you don't have WorldEdit installed.

Client Mod Commands

Run these in Minecraft:

---

Usage

Once connected, ask Claude to build things:

User: "Build me a small cottage near my position"
Claude: "I see these players online: Steve, Alex. Which player should I build near?"
User: "Steve"
Claude: *builds cottage using /fill and /setblock commands*


...