VibeCraft MCP Server

How to use

You interact with VibeCraft through an MCP client that connects to the server using either a local stdio mode or a remote HTTP/SSE mode. In stdio mode, your AI client runs alongside the MCP server and communicates through a shared process. In HTTP/SSE mode, you connect to a dedicated server endpoint to stream real-time logs and issue commands from multiple clients.

How to install

Prerequisites you need before installation: uv, Python 3.10 or newer, Docker Desktop with Docker Compose, and an MCP-compatible AI client (such as Claude Code, Claude Desktop, or Cursor). Then run the setup script to install dependencies, start PaperMC with WorldEdit in Docker, configure RCON, and create the AI client configuration.

Setup and run in stdio/Command Mode

In Command Mode, the AI client starts the MCP server as a subprocess when needed. Use the following configuration in your MCP client to run the local server process.

{
  "mcpServers": {
    "vibecraft": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.vibecraft.server"],
      "cwd": "/absolute/path/to/vibecraft/mcp-server",
      "env": {
        "VIBECRAFT_RCON_HOST": "127.0.0.1",
        "VIBECRAFT_RCON_PORT": "25575",
        "VIBECRAFT_RCON_PASSWORD": "your_password_from_setup"
      }
    }
  }
}

Setup and run in HTTP/SSE Server Mode

In SSE mode, run the standalone server from the project root so multiple AI clients can connect and you can see real-time logs.

# From the vibecraft root directory
cd mcp-server
./start-vibecraft.sh
```

Example server startup output:
```
🎮 VibeCraft MCP Server - HTTP/SSE Mode
   All 45 tools available
============================================================
📡 RCON Host: 127.0.0.1:25575
✅ RCON connected
✅ WorldEdit 7.3.17 detected
🚀 Server running at http://127.0.0.1:8765/sse

RCON and password setup

After setup completes, retrieve the generated RCON password and update your MCP client configurations with that value.

cat .rcon_password
```
Replace `your_password_from_setup` in the configs with this password.

Verify the connection

Restart your AI client completely and verify the integration by asking the AI to connect to the Minecraft server. If it responds with server information, you are ready to build.

Usage examples

Build, furnish, and shape terrain through natural-language prompts. The AI planning stage selects tools, scans the environment to prevent placement errors, and executes commands to create structures, interiors, and landscapes.

Notes on configuration and safety

Key safety features include command sanitization, coordinate bounds, async-prevention to avoid race conditions, and full WorldEdit undo/redo history. Spatial scanning prevents placement errors in furniture and roofs.

Examples of common setup configurations

Below are the configuration blocks you may use to connect your MCP client to the local SSE server and the stdio server. Copy the blocks that apply to your setup and adapt the paths and passwords to your environment.

Troubleshooting

If you encounter issues, restart the AI client completely, verify the RCON password, ensure the Minecraft server is running, and check that the MCP client configuration matches the active server settings.

Examples and templates

Use building templates, furniture catalogs, and terrain patterns to accelerate your projects. The system supports parametric templates and a knowledge base to guide material choices, proportions, and style.