Fundamental Labs/Minecraft Client

Controla bots de Minecraft con integración de IA. Requiere un servidor de Minecraft Java Edition.

GitHub
75
Prueba este MCPPatrocinado

Documentación

Fundamental Labs/Minecraft Client

Esta biblioteca es la biblioteca Cliente para una integración de Habilidades de Minecraft y MCP.

Fairies MCP Client (https://fairies.ai/) también admite conexión directa con un solo clic.

Características

  • Control total de Minecraft: Conecta agentes de IA a servidores de Minecraft y controla bots
  • 30 habilidades verificadas: Habilidades preconstruidas y probadas para tareas comunes de Minecraft
  • Conexión flexible: Conéctate a cualquier servidor de Minecraft con configuración opcional por bot
  • Soporte multi-bot: Gestiona múltiples bots simultáneamente
  • Estándar MCP: Compatible con cualquier cliente MCP (Claude Desktop, etc.)

Instalación

Llamada directa mediante npx (Recomendado)

npx --y -- @fundamentallabs/minecraft-mcp

Mediante npm (Recomendado)

npm install -g @fundamentallabs/minecraft-mcp

Desde el código fuente

git clone https://github.com/FundamentalLabs/minecraft-mcp.git
cd minecraft-mcp/minecraft-client/mcp-server
npm install
npm run build

Uso

Iniciando el servidor

Puedes iniciar el servidor MCP con configuraciones de conexión predeterminadas opcionales:

# Start with no defaults (connection specified per bot)
minecraft-mcp

# Start with default connection settings
minecraft-mcp -h play.example.com -p 25565

Opciones de línea de comandos

Options:
  -p, --port <port>  Minecraft server port (default: 25565)
  -h, --host <host>  Minecraft server host (default: localhost)
  --help            Display help

Integración con Claude Desktop o configuraciones JSON localmente

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

Para instalación remota (recomendado)

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "-- @fundamentallabs/minecraft-mcp"]
    }
  }
}

Si se ejecuta localmente desde el código fuente:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/minecraft-mcp/minecraft-client/mcp-server/dist/mcp-server.js"]
    }
  }
}

Reemplaza /path/to/minecraft-mcp con la ruta real donde clonaste el repositorio.

Integración con otros clientes MCP

El servidor utiliza transporte stdio y puede integrarse con cualquier cliente MCP:

# Using the MCP inspector for testing
cd minecraft-client/mcp-server
npx @modelcontextprotocol/inspector node dist/mcp-server.js -- -p 25565

Habilidades disponibles

Gestión de bots

  • joinGame - Genera un nuevo bot en el juego de Minecraft

    • username (obligatorio): Nombre de usuario del bot
    • host (opcional): Host del servidor (por defecto 'localhost' o la opción de línea de comandos)
    • port (opcional): Puerto del servidor (por defecto 25565 o la opción de línea de comandos)

  • leaveGame - Desconecta bot(s) del juego

    • username (opcional): Bot específico a desconectar
    • disconnectAll (opcional): Desconecta todos los bots si es verdadero

Movimiento y navegación

  • goToSomeone - Navega hacia otro jugador
  • goToKnownLocation - Navega a coordenadas específicas
  • runAway - Huye de amenazas
  • swimToLand - Nada hacia la tierra más cercana cuando esté en el agua

Combate y caza

  • attackSomeone - Ataca a jugadores, mobs o animales
  • hunt - Caza animales o mobs

Recolección de recursos

  • mineResource - Minar bloques o recursos específicos
  • harvestMatureCrops - Cosechar cultivos maduros de tierras de cultivo
  • pickupItem - Recoger objetos del suelo

Fabricación y fundición

  • craftItems - Fabricar objetos usando una mesa de crafteo
  • cookItem - Cocinar objetos en un horno
  • smeltItem - Fundir objetos en un horno
  • retrieveItemsFromNearbyFurnace - Obtener objetos fundidos del horno

Gestión de inventario

  • openInventory - Abrir el inventario del bot
  • equipItem - Equipar armadura, herramientas o armas
  • dropItem - Soltar objetos del inventario
  • giveItemToSomeone - Dar objetos a otro jugador

Construcción y agricultura

  • placeItemNearYou - Colocar bloques cerca del bot
  • prepareLandForFarming - Preparar tierra para la agricultura
  • useItemOnBlockOrEntity - Usar objetos en bloques o entidades

Supervivencia

  • eatFood - Comer comida para restaurar el hambre
  • rest - Descansar para recuperar salud
  • sleepInNearbyBed - Encontrar y dormir en una cama

Almacenamiento

  • openNearbyChest - Abrir un cofre cercano

Diversión

  • dance - Hacer que el bot baile

Visión

  • lookAround - Mirar alrededor y observar el entorno

Comunicación

  • readChat - Leer mensajes de chat recientes del servidor
  • sendChat - Enviar mensajes de chat o comandos al servidor

Construcción

  • buildSomething - Construir estructuras usando comandos de Minecraft (requiere permisos de trucos/operador). Soporta tanto matrices de comandos estáticas como código JavaScript dinámico.
  • buildPixelArt - Construir pixel art a partir de una imagen en Minecraft (requiere permisos de trucos/operador). Convierte una imagen en pixel art usando bloques de colores. El tamaño máximo es de 256x256 bloques.

Ejemplo de API

Cuando se integra con un cliente MCP, puedes controlar el bot de esta manera:

// First, spawn a bot
await client.callTool('joinGame', { username: 'MyBot' });

// Make the bot mine some wood
await client.callTool('mineResource', { name: 'oak_log', count: 10 });

// Craft wooden planks
await client.callTool('craftItems', { item: 'oak_planks', count: 40 });

// Navigate to coordinates
await client.callTool('goToKnownLocation', { x: 100, y: 64, z: 200 });

// Build a structure using commands (requires cheats) - Script mode
await client.callTool('buildSomething', {
  buildScript: [
    { command: "fill", x1: 0, y1: 64, z1: 0, x2: 10, y2: 64, z2: 10, block: "stone" },
    { command: "fill", x1: 1, y1: 65, z1: 1, x2: 9, y2: 68, z2: 9, block: "oak_planks" },
    { command: "setblock", x: 5, y: 65, z: 1, block: "oak_door" }
  ]
});

// Build dynamically with JavaScript (requires cheats) - Code mode
await client.callTool('buildSomething', {
  code: `
    // Build a pyramid centered on the bot
    const size = 10;
    for (let y = 0; y < size; y++) {
      const level = size - y;
      fill(pos.x - level, pos.y + y, pos.z - level,
           pos.x + level, pos.y + y, pos.z + level, 'sandstone');
      await wait(5); // Small delay between levels
    }
    log('Pyramid complete!');
  `
});

// Build pixel art from an image (requires cheats)
await client.callTool('buildPixelArt', {
  imagePath: 'https://example.com/logo.png',
  width: 64,
  height: 64,
  x: 0,
  y: 80,
  z: 100,
  facing: 'north'
});

// Read recent chat messages
await client.callTool('readChat', {
  count: 30,
  timeLimit: 300,  // Last 5 minutes
  filterType: 'chat'  // Only player messages
});

// Send a chat message
await client.callTool('sendChat', {
  message: 'Hello everyone! I am a bot.'
});

// Send a command
await client.callTool('sendChat', {
  message: '/time set day'
});

// Send a whisper
await client.callTool('sendChat', {
  message: '/msg Steve I can help you build!',
  delay: 1000  // Wait 1 second before sending
});

Arquitectura

El servidor MCP:

  • Utiliza transporte stdio para la comunicación con clientes de IA
  • Carga dinámicamente habilidades desde el directorio de habilidades verificadas
  • Gestiona múltiples instancias de bots (actualmente usa el primer bot para todas las operaciones)
  • Proporciona una interfaz unificada para todas las acciones del bot

Requisitos

  • Node.js >= 18.0.0
  • Un servidor de Minecraft (Edición Java) al que conectarse
  • Un cliente compatible con MCP (como Claude Desktop)

Solución de problemas

Error "Skill implementation not found"

El servidor MCP debe ejecutarse desde el repositorio clonado con las habilidades compiladas. Asegúrate de:

  1. Clonaste el repositorio completo
  2. Ejecutaste npm install en el directorio minecraft-client
  3. Ejecutaste npm run build en el directorio minecraft-client
  4. Estás ejecutando el servidor MCP desde el directorio correcto

El bot no se conecta

  • Asegúrate de que tu servidor de Minecraft esté en ejecución y sea accesible
  • Verifica que el puerto y el host sean correctos
  • Verifica que el servidor permita la versión de Minecraft que usa el bot

Las habilidades no funcionan

  • Asegúrate de que el bot se haya generado correctamente antes de usar habilidades
  • Algunas habilidades requieren objetos o condiciones específicas
  • Revisa la salida de consola del bot para ver mensajes de error

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una solicitud de extracción (Pull Request).

Licencia

MIT - consulta el archivo LICENSE para más detalles

Soporte

Para problemas y solicitudes de funciones, utiliza el rastreador de problemas de GitHub.

Pruebas

Para probar con el inspector MPC de Anthropic

'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'