Minecraft API and MCP

Adds a REST API to Minecraft and implements an MCP server so that you can play around with it in Claude Desktop or other LLMs.

Multiple MCP clients can use area reservations to keep their builds from overlapping. Reserve a cuboid, pass its lock_id on writes, and renew during long planning. Abandoned reservations expire after 15 minutes by default.

NBT placements (raw NBT, schematics, Starlark artifacts) can be dry-run and undone: dry_run reports what a placement would overwrite, and undo_build restores the blocks saved just before it was placed.

MCP can temporarily mark an area with a colored particle outline, vertical particle column, and floating label using mark_area. Vanilla clients work without a client mod, and markers expire automatically without changing terrain.

Docker architecture

The diagram follows docker-compose.yml and nginx.conf. The purple services run only when their Compose profiles are enabled. MCP fetches NBT artifacts from Starlark and the optional schematic service and sends placements to the Minecraft API. For the schematics profile, also set SCHEMATIC_SERVICE_URL=http://schematic-service:7080 in the MCP container’s environment; Compose currently configures only the Starlark URL.

Basics and setup

Running locally

For local development, run Fabric directly with Gradle and let your MCP client launch the Python MCP server over stdio. The certbot, nginx, minecraft, and mcp Compose services do not need to be running. You’ll need Java 21, uv, Python 3.12+, and Docker for PostgreSQL.

From the repository root, start the database and Fabric server:

docker compose up -d postgres
./gradlew runServer

runServer is the Fabric Loom Gradle task (shown under Fabric in IDE Gradle panels). On first launch, accept the Minecraft EULA in run/eula.txt, then run the task again. Leave the server running; the REST API is available at http://localhost:7070 and Minecraft at localhost:25565. The default database settings match the Compose PostgreSQL service on localhost:5432.

Install the MCP dependencies from a second terminal:

cd mcp
uv sync

Configure your MCP client to launch the following stdio server, replacing the project path with your checkout’s absolute path (and using the absolute path to uv if your client requires it):

{
  "mcpServers": {
    "minecraft-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/minecraft-mcp-api/mcp",
        "minecraft-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

The equivalent command from mcp/ is uv run minecraft-mcp --transport stdio.