⛏️ 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

Tool	Description
list-schematics	Lists all .schem files bundled with the server. The AI always calls this first before attempting any build.
schematic-info	Inspects a schematic file — shows dimensions, fill %, and top block types — without touching the world.
build-schematic	Builds the structure at given world coordinates using rapid /setblock commands. Accepts a short name ("smallhouse1") or a full path.

Supported Formats

Format	Extension	Notes
Sponge Schematic	.schem	✅ Primary format (WorldEdit, modern)
MCEdit Schematic	.schematic	✅ Legacy format, read-only
NBT Structure	.nbt	✅ Vanilla Minecraft structure files

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

Tool	Description
get-position	Get the bot's current world coordinates
move-to-position	Pathfind to specific coordinates
look-at	Make the bot look at coordinates
jump	Make the bot jump
move-in-direction	Move in a direction for a duration
fly-to	Fly directly to coordinates

Building (Schematic)

Tool	Description
list-schematics	★ List all bundled schematic files
schematic-info	Inspect a schematic's metadata
build-schematic	Instantly build a structure from a .schem file

Blocks

Tool	Description
place-block	Place a single block at a position
dig-block	Dig/break a block
get-block-info	Get info about a block at coordinates
find-blocks	Find nearby blocks of a given type

Inventory & Crafting

Tool	Description
list-inventory	List all items in the bot's inventory
find-item	Find a specific item
equip-item	Equip an item
list-recipes	List craftable recipes
craft-item	Craft an item
get-recipe	Get detailed recipe information
can-craft	Check if the bot can craft an item
smelt-item	Smelt items in a furnace

Entities & Chat

Tool	Description
find-entity	Find a nearby entity
send-chat	Send an in-game chat message
read-chat	Read recent chat messages
detect-gamemode	Detect the current game mode

---

🚀 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

Argument	Default	Description
--host	localhost	Minecraft server hostname
--port	25565	Minecraft server port
--username	ClaudeBot	Bot's in-game username

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