⛏️ Servidor MCP de Minecraft — Agente de Minecraft impulsado por IA

Creado por Soumyadeep, Líder de IA/ML

¿Qué es esto?

Es un agente de IA para Minecraft, impulsado por el Protocolo de Contexto de Modelo (MCP). Conecta cualquier cliente de IA compatible con MCP (Claude Desktop, Cursor, Kiro, Windsurf, etc.) directamente a tu mundo de Minecraft, convirtiendo a la IA en un bot totalmente capaz dentro del juego.

La IA puede moverse, construir, fabricar, chatear y ahora — generar instantáneamente estructuras completas a partir de archivos de esquema usando un solo comando.

Related MCP server: Minecraft MCP Server

✨ Novedades — Constructor de Esquemas (La función estrella)

La mayor adición a esta bifurcación es el Sistema de Constructor de Esquemas — un conjunto de 3 nuevas herramientas MCP que permiten a la IA construir estructuras masivas y complejas en segundos usando archivos .schem / .schematic.

En lugar de que la IA llame tediosamente a place-block cientos de veces (lento, propenso a errores, incorrecto), ahora:

1. Revisa su biblioteca incluida de archivos de esquema

2. Analiza el archivo para entender sus dimensiones y bloques

3. Dispara una secuencia de comandos /setblock a través del bot para construir toda la estructura instantáneamente en modo Creativo — sin inventario, sin búsqueda de rutas, sin fallos

Las 3 nuevas herramientas

Formatos soportados

Cómo lo usa la IA

La IA tiene instrucciones de revisar siempre la biblioteca incluida primero. Así que cuando dices:

"Construye una casa vikinga cerca de mí"

La IA hará:

1. Llamar a list-schematics → encuentra viking-house1

2. Llamar a schematic-info("viking-house1") → lee las dimensiones

3. Llamar a build-schematic("viking-house1", x, y, z) → la genera instantáneamente

Sin colocación manual de bloques. Sin geometría alucinada. Solo una estructura real, diseñada por humanos, en segundos.

🛠️ Referencia completa de herramientas

Movimiento

Construcción (Esquema)

Bloques

Inventario y Fabricación

Entidades y Chat

🚀 Guía de configuración

Requisitos previos

• Node.js ≥ 20.10.0

• Git

• Minecraft Java Edition (probado en 1.21.x)

• Un cliente de IA compatible con MCP (Claude Desktop, Cursor, Kiro, etc.)

Paso 1 — Clonar e instalar

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

Paso 2 — Construir

npm run build

Esto compila TypeScript a dist/main.js.

Paso 3 — Añadir archivos de esquema (Opcional pero recomendado)

Suelta cualquier archivo .schem en la carpeta schematics/ en la raíz del proyecto:

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

La IA los descubrirá automáticamente mediante list-schematics.

Paso 4 — Configurar tu cliente MCP

Claude Desktop

Abre File → Settings → Developer → Edit Config y añade:

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

Reemplaza C:\path\to\ con la ruta real en tu máquina.

Paso 5 — Iniciar Minecraft

1. Inicia Minecraft Java Edition

2. Abre o crea un mundo de un solo jugador

3. Presiona ESC → Abrir en LAN

4. Anota el número de puerto mostrado (usualmente 25565)

5. En el chat, dale al bot permisos de operador:

   /op ClaudeBot

   ⚠️ Los permisos de operador son necesarios para que funcionen los comandos /setblock (usados por el constructor de esquemas)

Paso 6 — Reinicia tu cliente de IA y prueba

Reinicia completamente tu cliente MCP (ciérralo desde la bandeja del sistema si es necesario). El bot debería unirse al juego automáticamente.

Prompt de prueba:

"Comprueba qué esquemas están disponibles y construye la casa pequeña en mi posición actual."

📦 Añadir más esquemas

La biblioteca de esquemas es solo una carpeta. Para añadir más estructuras:

1. Encuentra archivos .schem en línea:

   • Planet Minecraft — busca y filtra por "schematic"

   • Minecraft-Schematics.com

   • El comando integrado de WorldEdit //copy + //schem save dentro del juego

2. Suelta el archivo en minecraft-mcp-server/schematics/

3. Reinicia el servidor MCP

La IA lo detecta inmediatamente — no se necesitan cambios de código.

⚙️ Argumentos del servidor

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

🏗️ Arquitectura

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

Bibliotecas clave:

• mineflayer — Framework de bot de Minecraft

• prismarine-schematic — Analizador de archivos de esquema

• mineflayer-pathfinder — Búsqueda de rutas

• @modelcontextprotocol/sdk — SDK de servidor MCP

Bifurcado y extendido desde yuniko-software/minecraft-mcp-server

🗺️ Hoja de ruta

• [ ] mode: "bot_place" — construcción física en modo supervivencia mediante mineflayer-builder

• [ ] Soporte de formato .litematic mediante @kleppe/litematic-reader

• [ ] Herramienta search-and-build — buscar y descargar esquemas por palabra clave

• [ ] run-builder-script — ejecutar scripts de construcción procedimental (para pirámides, cúpulas, etc.)

• [ ] Herramientas de cofre y almacenamiento

• [ ] Herramientas de comercio con aldeanos

• [ ] Herramientas de combate y supervivencia

🤝 Contribuyendo

¡Las solicitudes de extracción (pull requests) son bienvenidas! Consulta CONTRIBUTING.md para ver las directrices.

📄 Licencia

MIT — ver LICENSE

Creado y extendido por Soumyadip Debnath, Líder de IA/ML Proyecto original de Yuniko Software