Fundamental Labs/Minecraft Client

Fundamental Labs/Minecraft 客户端

此库是用于 Minecraft 游戏技能和 MCP 集成的客户端库。

Fairies MCP 客户端（https://fairies.ai/）也支持一键直接连接。

功能

• 完整的 Minecraft 控制：将 AI Agent 连接到 Minecraft 服务端并控制机器人
• 30 项经过验证的技能：为常见的 Minecraft 任务预构建并经过测试的技能
• 灵活连接：连接到任意 Minecraft 服务端，并可选择为每个机器人单独配置
• 多机器人支持：同时管理多个机器人
• MCP 标准：兼容任何 MCP 客户端（Claude Desktop 等）

安装

通过 npx 直接调用（推荐）

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

通过 npm 安装（推荐）

npm install -g @fundamentallabs/minecraft-mcp

从源代码安装

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

用法

启动服务

你可以使用可选的默认连接设置启动 MCP 服务：

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

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

命令行选项

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

与 Claude Desktop 或本地 JSON 配置集成

将以下内容添加到 Claude Desktop 配置文件（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

远程安装（推荐）

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

如果从源代码在本地运行：

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

将 /path/to/minecraft-mcp 替换为你克隆此仓库的实际路径。

与其他 MCP 客户端集成

此服务使用 stdio 传输，可与任何 MCP 客户端集成：

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

可用技能

机器人管理

• joinGame - 在 Minecraft 游戏中生成一个新机器人

  • username（必需）：机器人的用户名
  • host（可选）：服务端主机（默认为“localhost”或命令行选项）
  • port（可选）：服务端端口（默认为 25565 或命令行选项）

• leaveGame - 断开机器人与游戏的连接

  • username（可选）：要断开的特定机器人
  • disconnectAll（可选）：若为 true，则断开所有机器人的连接

移动与导航

• goToSomeone - 导航至另一名玩家处
• goToKnownLocation - 导航至指定坐标
• runAway - 逃离威胁
• swimToLand - 在水中时游向最近的陆地

战斗与狩猎

• attackSomeone - 攻击玩家、生物或动物
• hunt - 狩猎动物或生物

资源采集

• mineResource - 挖掘指定方块或资源
• harvestMatureCrops - 收获农田中的成熟作物
• pickupItem - 捡起地上的物品

制作与熔炼

• craftItems - 使用工作台制作物品
• cookItem - 在熔炉中烹饪物品
• smeltItem - 在熔炉中熔炼物品
• retrieveItemsFromNearbyFurnace - 从熔炉中取出已熔炼的物品

物品栏管理

• openInventory - 打开机器人的物品栏
• equipItem - 装备盔甲、工具或武器
• dropItem - 丢弃物品栏中的物品
• giveItemToSomeone - 将物品交给另一名玩家

建造与耕种

• placeItemNearYou - 在机器人附近放置方块
• prepareLandForFarming - 开垦土地以便耕种
• useItemOnBlockOrEntity - 对方块或实体使用物品

生存

• eatFood - 进食以恢复饥饿值
• rest - 休息以恢复生命值
• sleepInNearbyBed - 寻找并在床上睡觉

储存

• openNearbyChest - 打开附近的箱子

娱乐

• dance - 让机器人跳舞

视觉

• lookAround - 环顾四周并观察环境

通信

• readChat - 读取服务端最近的聊天消息
• sendChat - 向服务端发送聊天消息或命令

建造

• buildSomething - 使用 Minecraft 命令建造结构（需要作弊权限/管理员权限）。支持静态命令数组和动态 JavaScript 代码。
• buildPixelArt - 在 Minecraft 中根据图像建造像素艺术（需要作弊权限/管理员权限）。使用彩色方块将图像转换为像素艺术。最大尺寸为 256x256 个方块。

API 示例

集成 MCP 客户端后，你可以这样控制机器人：

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

架构

MCP 服务：

• 使用 stdio 传输与 AI 客户端通信
• 从经过验证的技能目录中动态加载技能
• 管理多个机器人实例（目前所有操作都使用第一个机器人）
• 为所有机器人操作提供统一接口

要求

• Node.js >= 18.0.0
• 要连接的 Minecraft 服务器（Java Edition）
• 兼容 MCP 的客户端（如 Claude Desktop）

故障排除

“未找到技能实现”错误

MCP 服务需要从克隆的仓库中运行，并且仓库中必须包含已构建的技能。请确保你已：

1. 克隆完整仓库
2. 在 minecraft-client 目录中运行 npm install
3. 在 minecraft-client 目录中运行 npm run build
4. 从正确的目录运行 MCP 服务

机器人无法连接

• 确保 Minecraft 服务器正在运行且可访问
• 检查端口和主机是否正确
• 确认服务器允许机器人使用的 Minecraft 版本

技能无法使用

• 使用技能前，请确保机器人已成功生成
• 某些技能需要特定物品或条件
• 检查机器人的控制台输出中是否有错误消息

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT——详情请参阅 LICENSE 文件

支持

如需反馈问题或提出功能请求，请使用 GitHub issue 跟踪器。

测试

使用 Anthropic MPC inspector 进行测试

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