Fundamental Labs/Minecraft Client

Controle bots de Minecraft com integração de IA. Requer um servidor Minecraft Java Edition.

GitHub
75
Experimente este MCPPatrocinado

Documentação

Fundamental Labs/Minecraft Client

Esta biblioteca é a biblioteca Cliente para uma integração de Habilidades de Jogo Minecraft e MCP.

O Fairies MCP Client (https://fairies.ai/) também suporta conexão direta com um único clique.

Recursos

  • Controle Total do Minecraft: Conecte agentes de IA a servidores Minecraft e controle bots
  • 30 Habilidades Verificadas: Habilidades pré-construídas e testadas para tarefas comuns do Minecraft
  • Conexão Flexível: Conecte-se a qualquer servidor Minecraft com configuração opcional por bot
  • Suporte a Múltiplos Bots: Gerencie vários bots simultaneamente
  • Padrão MCP: Compatível com qualquer cliente MCP (Claude Desktop, etc.)

Instalação

Chamada direta via npx (Recomendado)

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

Via npm (Recomendado)

npm install -g @fundamentallabs/minecraft-mcp

A partir do código-fonte

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

Uso

Iniciando o Servidor

Você pode iniciar o servidor MCP com configurações de conexão padrão opcionais:

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

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

Opções de Linha de Comando

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

Integração com Claude Desktop ou configurações JSON localmente

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

Para instalação remota (recomendado)

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

Se estiver executando localmente a partir do código-fonte:

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

Substitua /path/to/minecraft-mcp pelo caminho real onde você clonou o repositório.

Integração com Outros Clientes MCP

O servidor usa transporte stdio e pode ser integrado com qualquer cliente MCP:

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

Habilidades Disponíveis

Gerenciamento de Bots

  • joinGame - Cria um novo bot no jogo Minecraft

    • username (obrigatório): Nome de usuário do bot
    • host (opcional): Host do servidor (padrão: 'localhost' ou opção de linha de comando)
    • port (opcional): Porta do servidor (padrão: 25565 ou opção de linha de comando)

  • leaveGame - Desconecta bot(s) do jogo

    • username (opcional): Bot específico para desconectar
    • disconnectAll (opcional): Desconecta todos os bots se verdadeiro

Movimento e Navegação

  • goToSomeone - Navega até outro jogador
  • goToKnownLocation - Navega até coordenadas específicas
  • runAway - Foge de ameaças
  • swimToLand - Nada até a terra mais próxima quando estiver na água

Combate e Caça

  • attackSomeone - Ataca jogadores, mobs ou animais
  • hunt - Caça animais ou mobs

Coleta de Recursos

  • mineResource - Minera blocos ou recursos específicos
  • harvestMatureCrops - Colhe culturas maduras da terra agrícola
  • pickupItem - Coleta itens do chão

Criação e Fundição

  • craftItems - Cria itens usando uma mesa de criação
  • cookItem - Cozinha itens em uma fornalha
  • smeltItem - Funde itens em uma fornalha
  • retrieveItemsFromNearbyFurnace - Obtém itens fundidos da fornalha

Gerenciamento de Inventário

  • openInventory - Abre o inventário do bot
  • equipItem - Equipa armaduras, ferramentas ou armas
  • dropItem - Descarta itens do inventário
  • giveItemToSomeone - Dá itens a outro jogador

Construção e Agricultura

  • placeItemNearYou - Coloca blocos perto do bot
  • prepareLandForFarming - Prepara a terra para agricultura
  • useItemOnBlockOrEntity - Usa itens em blocos ou entidades

Sobrevivência

  • eatFood - Come comida para restaurar a fome
  • rest - Descansa para recuperar saúde
  • sleepInNearbyBed - Encontra e dorme em uma cama

Armazenamento

  • openNearbyChest - Abre um baú próximo

Diversão

  • dance - Faz o bot dançar

Visão

  • lookAround - Olha ao redor e observa o ambiente

Comunicação

  • readChat - Lê mensagens recentes do chat do servidor
  • sendChat - Envia mensagens de chat ou comandos ao servidor

Construção

  • buildSomething - Constrói estruturas usando comandos do Minecraft (requer permissões de cheats/operador). Suporta tanto arrays de comandos estáticos quanto código JavaScript dinâmico.
  • buildPixelArt - Constrói pixel art a partir de uma imagem no Minecraft (requer permissões de cheats/operador). Converte uma imagem em pixel art usando blocos coloridos. O tamanho máximo é 256x256 blocos.

Exemplo de API

Quando integrado a um cliente MCP, você pode controlar o bot assim:

// 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
});

Arquitetura

O servidor MCP:

  • Usa transporte stdio para comunicação com clientes de IA
  • Carrega dinamicamente habilidades do diretório de habilidades verificadas
  • Gerencia múltiplas instâncias de bots (atualmente usa o primeiro bot para todas as operações)
  • Fornece uma interface unificada para todas as ações do bot

Requisitos

  • Node.js >= 18.0.0
  • Um servidor Minecraft (Edição Java) para conectar
  • Um cliente compatível com MCP (como Claude Desktop)

Solução de Problemas

Erro "Skill implementation not found"

O servidor MCP precisa ser executado a partir do repositório clonado com as habilidades compiladas. Certifique-se de que:

  1. Você clonou o repositório completo
  2. Executou npm install no diretório minecraft-client
  3. Executou npm run build no diretório minecraft-client
  4. Está executando o servidor MCP a partir do diretório correto

O bot não conecta

  • Certifique-se de que seu servidor Minecraft está em execução e acessível
  • Verifique se a porta e o host estão corretos
  • Confirme que o servidor permite a versão do Minecraft que o bot usa

Habilidades não funcionando

  • Certifique-se de que o bot foi criado com sucesso antes de usar as habilidades
  • Algumas habilidades exigem itens ou condições específicas
  • Verifique a saída do console do bot para mensagens de erro

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

MIT - veja o arquivo LICENSE para detalhes

Suporte

Para problemas e solicitações de recursos, use o rastreador de problemas do GitHub.

Testes

Para testar com o inspetor Anthropic MPC

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