⛏️ Minecraft MCP Server — AI-Powered Minecraft Agent

Built by Soumyadeep, AI/ML Lead

What Is This?

This is an AI agent for Minecraft, powered by the Model Context Protocol (MCP). It connects any MCP-compatible AI client (Claude Desktop, Cursor, Kiro, Windsurf, etc.) directly to your Minecraft world, turning the AI into a fully capable in-game bot.

The AI can move, build, craft, chat, and now — instantly spawn entire structures from schematic files using a single command.

✨ What's New — Schematic Builder (The Star Feature)

The biggest addition to this fork is the Schematic Builder System — a set of 3 new MCP tools that let the AI construct massive, complex structures in seconds using .schem / .schematic files.

Instead of the AI tediously calling place-block hundreds of times (slow, error-prone, wrong), it now:

1. Checks its bundled library of schematic files
2. Parses the file to understand its dimensions and blocks
3. Fires a stream of /setblock commands via the bot to build the entire structure instantly in Creative mode — no inventory, no pathfinding, no failures

The 3 New Tools

Supported Formats

How the AI Uses It

The AI is instructed to always check the bundled library first. So when you say:

"Build a viking house near me"

The AI will:

1. Call list-schematics → finds viking-house1
2. Call schematic-info("viking-house1") → reads dimensions
3. Call build-schematic("viking-house1", x, y, z) → spawns it instantly

No manual block placement. No hallucinated geometry. Just a real, human-designed structure in seconds.

🛠️ Full Tool Reference

Movement

Building (Schematic)

Blocks

Inventory & Crafting

Entities & Chat

🚀 Setup Guide

Prerequisites

• Node.js ≥ 20.10.0
• Git
• Minecraft Java Edition (tested on 1.21.x)
• An MCP-compatible AI client (Claude Desktop, Cursor, Kiro, etc.)

Step 1 — Clone & Install

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

Step 2 — Build

npm run build

This compiles TypeScript to dist/main.js.

Step 3 — Add Schematic Files (Optional but Recommended)

Drop any .schem files into the schematics/ folder at the root of the project:

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

The AI will automatically discover them via list-schematics.

Step 4 — Configure Your MCP Client

Claude Desktop

Open File → Settings → Developer → Edit Config and add:

{
  "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"
    }
  }
}

Replace C:\\path\\to\\ with the actual path on your machine.

Step 5 — Start Minecraft

1. Launch Minecraft Java Edition
2. Open or create a Singleplayer world
3. Press ESC → Open to LAN
4. Note the port number shown (usually 25565)
5. In the chat, give the bot operator permissions:

   /op ClaudeBot
   

   ⚠️ Operator permissions are required for /setblock commands to work (used by the schematic builder)

Step 6 — Restart Your AI Client & Test

Fully restart your MCP client (close from system tray if needed). The bot should join the game automatically.

Test prompt:

"Check what schematics are available and build the smallhouse at my current position."

📦 Adding More Schematics

The schematic library is just a folder. To add more structures:

1. Find .schem files online:

   • Planet Minecraft — search and filter by "schematic"
   • Minecraft-Schematics.com
   • WorldEdit's built-in //copy + //schem save command in-game

2. Drop the file into minecraft-mcp-server/schematics/

3. Restart the MCP server

The AI immediately picks it up — no code changes needed.

⚙️ Server Arguments

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

🏗️ Architecture

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

Key Libraries:

• mineflayer — Minecraft bot framework
• prismarine-schematic — Schematic file parser
• mineflayer-pathfinder — Pathfinding
• @modelcontextprotocol/sdk — MCP server SDK

Forked and extended from yuniko-software/minecraft-mcp-server

🗺️ Roadmap

• mode: "bot_place" — physical survival-mode building via mineflayer-builder
• .litematic format support via @kleppe/litematic-reader
• search-and-build tool — scrape and download schematics by keyword
• run-builder-script — execute procedural build scripts (for pyramids, domes, etc.)
• Chest & storage tools
• Villager trading tools
• Combat & survival tools

🤝 Contributing

Pull requests are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — see LICENSE

Built and extended by Soumyadip Debnath, AI/ML Lead Original project by Yuniko Software