⛏️ Minecraft MCP Server — ИИ-агент для Minecraft

Создано Soumyadeep, AI/ML Lead

Что это такое?

Это ИИ-агент для Minecraft, работающий на базе Model Context Protocol (MCP). Он подключает любой MCP-совместимый ИИ-клиент (Claude Desktop, Cursor, Kiro, Windsurf и др.) напрямую к вашему миру Minecraft, превращая ИИ в полноценного внутриигрового бота.

ИИ может перемещаться, строить, создавать предметы, общаться в чате, а теперь — мгновенно создавать целые структуры из файлов схем (schematics) с помощью одной команды.

Related MCP server: Renge Bot

✨ Что нового — Конструктор схем (Главная функция)

Самое большое дополнение в этом форке — система конструктора схем (Schematic Builder System) — набор из 3 новых инструментов MCP, которые позволяют ИИ возводить массивные, сложные структуры за секунды, используя файлы .schem / .schematic.

Вместо того чтобы ИИ утомительно вызывал place-block сотни раз (медленно, подвержено ошибкам, неточно), теперь он:

1. Проверяет свою встроенную библиотеку файлов схем

2. Анализирует файл, чтобы понять его размеры и блоки

3. Отправляет поток команд /setblock через бота, чтобы мгновенно построить всю структуру в творческом режиме (Creative mode) — без инвентаря, без поиска пути, без сбоев

3 новых инструмента

Поддерживаемые форматы

Как ИИ использует это

ИИ проинструктирован всегда сначала проверять встроенную библиотеку. Поэтому, когда вы говорите:

"Построй дом викингов рядом со мной"

ИИ сделает следующее:

1. Вызовет list-schematics → найдет viking-house1

2. Вызовет schematic-info("viking-house1") → прочитает размеры

3. Вызовет build-schematic("viking-house1", x, y, z) → мгновенно создаст его

Никакой ручной расстановки блоков. Никакой галлюцинирующей геометрии. Просто настоящая, спроектированная человеком структура за секунды.

🛠️ Полный справочник инструментов

Перемещение

Строительство (Схемы)

Блоки

Инвентарь и крафт

Сущности и чат

🚀 Руководство по установке

Предварительные требования

• Node.js ≥ 20.10.0

• Git

• Minecraft Java Edition (протестировано на 1.21.x)

• MCP-совместимый ИИ-клиент (Claude Desktop, Cursor, Kiro и др.)

Шаг 1 — Клонирование и установка

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

Шаг 2 — Сборка

npm run build

Это скомпилирует TypeScript в dist/main.js.

Шаг 3 — Добавление файлов схем (необязательно, но рекомендуется)

Поместите любые файлы .schem в папку schematics/ в корне проекта:

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

ИИ автоматически обнаружит их через list-schematics.

Шаг 4 — Настройка вашего MCP-клиента

Claude Desktop

Откройте File → Settings → Developer → Edit Config и добавьте:

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

Замените C:\path\to\ на реальный путь на вашем компьютере.

Шаг 5 — Запуск Minecraft

1. Запустите Minecraft Java Edition

2. Откройте или создайте одиночный мир

3. Нажмите ESC → Открыть для сети

4. Запишите номер порта (обычно 25565)

5. В чате дайте боту права оператора:

   /op ClaudeBot

   ⚠️ Права оператора обязательны для работы команд /setblock (используются конструктором схем)

Шаг 6 — Перезапустите ИИ-клиент и протестируйте

Полностью перезапустите MCP-клиент (при необходимости закройте из системного трея). Бот должен автоматически присоединиться к игре.

Тестовый запрос:

"Проверь, какие схемы доступны, и построй smallhouse в моей текущей позиции."

📦 Добавление новых схем

Библиотека схем — это просто папка. Чтобы добавить больше структур:

1. Найдите файлы .schem в интернете:

   • Planet Minecraft — ищите и фильтруйте по "schematic"

   • Minecraft-Schematics.com

   • Встроенная команда WorldEdit //copy + //schem save в игре

2. Поместите файл в minecraft-mcp-server/schematics/

3. Перезапустите MCP-сервер

ИИ сразу же подхватит их — изменения в коде не требуются.

⚙️ Аргументы сервера

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

🏗️ Архитектура

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

Ключевые библиотеки:

• mineflayer — фреймворк для ботов Minecraft

• prismarine-schematic — парсер файлов схем

• mineflayer-pathfinder — поиск пути

• @modelcontextprotocol/sdk — SDK сервера MCP

Форк и расширение проекта yuniko-software/minecraft-mcp-server

🗺️ Дорожная карта

• [ ] mode: "bot_place" — физическое строительство в режиме выживания через mineflayer-builder

• [ ] Поддержка формата .litematic через @kleppe/litematic-reader

• [ ] Инструмент search-and-build — поиск и скачивание схем по ключевым словам

• [ ] run-builder-script — выполнение процедурных скриптов строительства (для пирамид, куполов и т.д.)

• [ ] Инструменты для сундуков и хранилищ

• [ ] Инструменты для торговли с жителями

• [ ] Инструменты для боя и выживания

🤝 Участие в разработке

Пул-реквесты приветствуются! См. CONTRIBUTING.md для получения инструкций.

📄 Лицензия

MIT — см. LICENSE

Создано и расширено Soumyadip Debnath, AI/ML Lead Оригинальный проект от Yuniko Software