⛏️ Minecraft MCP-Server — KI-gestützter Minecraft-Agent

Erstellt von Soumyadeep, AI/ML Lead

Was ist das?

Dies ist ein KI-Agent für Minecraft, basierend auf dem Model Context Protocol (MCP). Er verbindet jeden MCP-kompatiblen KI-Client (Claude Desktop, Cursor, Kiro, Windsurf usw.) direkt mit deiner Minecraft-Welt und macht die KI zu einem voll funktionsfähigen In-Game-Bot.

Die KI kann sich bewegen, bauen, craften, chatten und jetzt — sofort ganze Strukturen aus Schematic-Dateien spawnen mit einem einzigen Befehl.

Related MCP server: Minecraft MCP Server

✨ Was ist neu — Schematic Builder (Das Highlight-Feature)

Die größte Neuerung in diesem Fork ist das Schematic Builder System — eine Reihe von 3 neuen MCP-Tools, mit denen die KI in Sekundenschnelle massive, komplexe Strukturen mithilfe von .schem / .schematic-Dateien errichten kann.

Anstatt dass die KI mühsam hunderte Male place-block aufruft (langsam, fehleranfällig, falsch), macht sie jetzt Folgendes:

1. Überprüft ihre gebündelte Bibliothek an Schematic-Dateien

2. Analysiert die Datei, um deren Abmessungen und Blöcke zu verstehen

3. Sendet einen Strom von /setblock-Befehlen über den Bot, um die gesamte Struktur sofort im Kreativmodus zu bauen — kein Inventar, kein Pathfinding, keine Fehler

Die 3 neuen Tools

Unterstützte Formate

Wie die KI es verwendet

Die KI ist angewiesen, immer zuerst die gebündelte Bibliothek zu prüfen. Wenn du also sagst:

"Baue ein Wikingerhaus in meiner Nähe"

Dann wird die KI:

1. list-schematics aufrufen → findet viking-house1

2. schematic-info("viking-house1") aufrufen → liest die Abmessungen

3. build-schematic("viking-house1", x, y, z) aufrufen → spawnt es sofort

Kein manuelles Platzieren von Blöcken. Keine halluzinierte Geometrie. Einfach eine echte, von Menschen entworfene Struktur in Sekunden.

🛠️ Vollständige Tool-Referenz

Bewegung

Bauen (Schematic)

Blöcke

Inventar & Crafting

Entitäten & Chat

🚀 Einrichtungsanleitung

Voraussetzungen

• Node.js ≥ 20.10.0

• Git

• Minecraft Java Edition (getestet mit 1.21.x)

• Ein MCP-kompatibler KI-Client (Claude Desktop, Cursor, Kiro usw.)

Schritt 1 — Klonen & Installieren

git clone https://github.com/soumyadeo/minecraft-mcp-server.git
cd minecraft-mcp-server
npm install

Schritt 2 — Bauen

npm run build

Dies kompiliert TypeScript zu dist/main.js.

Schritt 3 — Schematic-Dateien hinzufügen (Optional, aber empfohlen)

Lege beliebige .schem-Dateien in den schematics/-Ordner im Stammverzeichnis des Projekts:

minecraft-mcp-server/
  schematics/
    smallhouse1.schem       ← already included
    viking-house1.schematic ← already included
    my-castle.schem         ← add your own!

Die KI wird sie automatisch über list-schematics entdecken.

Schritt 4 — Konfiguriere deinen MCP-Client

Claude Desktop

Öffne Datei → Einstellungen → Entwickler → Konfiguration bearbeiten und füge hinzu:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ]
    }
  }
}

Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ],
      "type": "stdio"
    }
  }
}

Ersetze C:\\pfad\\zu\\ durch den tatsächlichen Pfad auf deinem Computer.

Schritt 5 — Minecraft starten

1. Starte Minecraft Java Edition

2. Öffne oder erstelle eine Einzelspieler-Welt

3. Drücke ESC → Im LAN öffnen

4. Notiere die angezeigte Portnummer (normalerweise 25565)

5. Gib dem Bot im Chat Operator-Rechte:

   /op ClaudeBot

   ⚠️ Operator-Rechte sind erforderlich, damit /setblock-Befehle funktionieren (werden vom Schematic Builder verwendet)

Schritt 6 — Starte deinen KI-Client neu & Teste

Starte deinen MCP-Client vollständig neu (schließe ihn ggf. aus der Taskleiste). Der Bot sollte automatisch dem Spiel beitreten.

Test-Prompt:

"Prüfe, welche Schematics verfügbar sind, und baue das smallhouse an meiner aktuellen Position."

📦 Weitere Schematics hinzufügen

Die Schematic-Bibliothek ist nur ein Ordner. Um weitere Strukturen hinzuzufügen:

1. Finde .schem-Dateien online:

   • Planet Minecraft — suche und filtere nach "schematic"

   • Minecraft-Schematics.com

   • WorldEdits eingebauter //copy + //schem save-Befehl im Spiel

2. Lege die Datei in minecraft-mcp-server/schematics/ ab

3. Starte den MCP-Server neu

Die KI erkennt sie sofort — keine Codeänderungen erforderlich.

⚙️ Server-Argumente

node dist/main.js --host localhost --port 25565 --username ClaudeBot

🏗️ Architektur

src/
  main.ts                   — MCP server entry point, tool registration
  bot-connection.ts         — Mineflayer bot lifecycle management
  tool-factory.ts           — MCP tool registration wrapper
  tools/
    schematic-tools.ts      — ★ Schematic builder (new)
    block-tools.ts          — Block placement & digging
    position-tools.ts       — Movement & pathfinding
    inventory-tools.ts      — Inventory management
    crafting-tools.ts       — Recipe lookup & crafting
    furnace-tools.ts        — Smelting
    entity-tools.ts         — Entity detection
    chat-tools.ts           — In-game chat
    flight-tools.ts         — Flight control
    gamestate-tools.ts      — Game mode detection
schematics/                 — Bundled schematic file library
  smallhouse1.schem
  viking-house1.schematic

Wichtige Bibliotheken:

• mineflayer — Minecraft-Bot-Framework

• prismarine-schematic — Schematic-Datei-Parser

• mineflayer-pathfinder — Pathfinding

• @modelcontextprotocol/sdk — MCP-Server-SDK

Geforkt und erweitert von yuniko-software/minecraft-mcp-server

🗺️ Roadmap

• [ ] mode: "bot_place" — physisches Bauen im Survival-Modus via mineflayer-builder

• [ ] .litematic-Formatunterstützung via @kleppe/litematic-reader

• [ ] search-and-build-Tool — Schematics nach Stichwort suchen und herunterladen

• [ ] run-builder-script — prozedurale Bauskripte ausführen (für Pyramiden, Kuppeln usw.)

• [ ] Truhen- & Lager-Tools

• [ ] Dorfbewohner-Handels-Tools

• [ ] Kampf- & Survival-Tools

🤝 Mitwirken

Pull Requests sind willkommen! Siehe CONTRIBUTING.md für Richtlinien.

📄 Lizenz

MIT — siehe LICENSE

Erstellt und erweitert von Soumyadip Debnath, AI/ML Lead Ursprüngliches Projekt von Yuniko Software