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

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

• 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

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

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

In Minecraft chat:

/vibecraft allow

cd mcp-server
uv sync

Add to ~/.claude.json:

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

cd mcp-server
./start-vibecraft.sh

cd agent
claude

You're ready! Ask Claude to build something:

"Build me a small stone cottage"

See docs/SETUP_GUIDE.md for:

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

• 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.

Run these in Minecraft:

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*

For the best building experience, run Claude from the agent/ folder:

cd agent
claude

This folder has:

• Pre-configured .mcp.json
• Building skills and workflows
• Material guides and templates

Make sure you're using the exact player name (case-sensitive).

The client mod might not be capturing command output. Update to the latest mod version.

The block doesn't exist in your Minecraft version. Use blocks from your version.

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

1. Make sure Minecraft is running with the mod
2. Run /vibecraft status to check the bridge
3. Run /vibecraft allow to enable AI control
4. Check that ports match (default: 8766)

The client mod approach above works with any server. For headless environments or server-side automation without a Minecraft client, you can use direct RCON:

./setup-all.sh  # Starts Minecraft server in Docker with RCON

This is useful for CI/testing but has limitations (no multiplayer, requires server access). See docs/CONFIGURATION.md for details.

vibecraft/
├── agent/                    # Run Claude here to BUILD in Minecraft
│   ├── .claude/skills/       # Building skills and workflows
│   ├── context/              # Material guides, templates
│   ├── .mcp.json             # MCP server config
│   └── CLAUDE.md             # Agent system prompt
│
├── client-mod/               # Fabric client mod (Java)
│   ├── src/                  # Mod source code
│   ├── build.gradle          # Gradle build config
│   └── README.md             # Mod-specific docs
│
├── mcp-server/               # MCP server (Python)
│   ├── src/vibecraft/        # Server source code
│   ├── server_http.py        # SSE mode entry point
│   ├── start-vibecraft.sh    # SSE mode launcher
│   └── pyproject.toml        # Python dependencies
│
└── README.md                 # This file

Contributions welcome! See CONTRIBUTING.md.

MIT License - see LICENSE.

• 📧 Email: evan@amentilabs.com
• 🐛 Issues: GitHub Issues

Happy building! 🧱