# ⛏️ Minecraft MCP Server — AI-Powered Minecraft Agent

> **Built by [Soumyadeep](https://github.com/soumyacodes007), AI/ML Lead**


---

## What Is This?

This is an **AI agent for Minecraft**, powered by the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol). 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

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

### Step 2 — Build

```bash
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:

```json
{
  "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`)
```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](https://www.planetminecraft.com/projects/) — search and filter by "schematic"
   - [Minecraft-Schematics.com](https://www.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 |

```bash
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`](https://github.com/PrismarineJS/mineflayer) — Minecraft bot framework
- [`prismarine-schematic`](https://github.com/PrismarineJS/prismarine-schematic) — Schematic file parser
- [`mineflayer-pathfinder`](https://github.com/PrismarineJS/mineflayer-pathfinder) — Pathfinding
- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) — MCP server SDK
> Forked and extended from [yuniko-software/minecraft-mcp-server](https://github.com/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](CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT — see [LICENSE](LICENSE)

---

> **Built and extended by Soumyadip Debnath, AI/ML Lead**
> Original project by [Yuniko Software](https://github.com/yuniko-software/minecraft-mcp-server)