Fundamental Labs/Minecraft 客户端

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

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

功能

• 完全控制Minecraft：将AI代理连接到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服务器：

# 不使用默认设置（每个机器人指定连接）
minecraft-mcp

# 使用默认连接设置
minecraft-mcp -h play.example.com -p 25565

命令行选项

选项:
  -p, --port <port>  Minecraft服务器端口（默认：25565）
  -h, --host <host>  Minecraft服务器主机（默认：localhost）
  --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客户端集成：

# 使用MCP检查器进行测试
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（可选）：如果为真，则断开所有机器人

移动与导航

• 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客户端集成时，你可以这样控制机器人：

// 首先，生成一个机器人
await client.callTool('joinGame', { username: 'MyBot' });

// 让机器人开采一些木材
await client.callTool('mineResource', { name: 'oak_log', count: 1 0});

// 制作木板
await client.callTool('craftItems', { item: 'oak_planks', count: 40 });

// 导航到坐标
await client.callTool('goToKnownLocation', { x: 100, y: 64, z: 200 });

// 使用命令建造结构（需要作弊） - 脚本模式
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" }
  ]
});

// 使用JavaScript动态建造（需要作弊） - 代码模式
await client.callTool('buildSomething', {
  code: `
    // 在机器人中心建造金字塔
    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); // 层级之间的小延迟
    }
    log('金字塔完成！');
  `
});

// 根据图像建造像素艺术（需要作弊）
await client.callTool('buildPixelArt', {
  imagePath: 'https://example.com/logo.png',
  width: 64,
  height: 64,
  x: 0,
  y: 80,
  z: 100,
  facing: 'north'
});

// 读取最新的聊天消息
await client.callTool('readChat', {
  count: 30,
  timeLimit: 300,  // 最近5分钟
  filterType: 'chat'  // 只有玩家的消息
});

// 发送一条聊天消息
await client.callTool('sendChat', {
  message: '大家好！我是机器人。'
});

// 发送一个命令
await client.callTool('sendChat', {
  message: '/time set day'
});

// 发送一个私信
await client.callTool('sendChat', {
  message: '/msg Steve 我可以帮助你建造！',
  delay: 1000  // 发送前等待1秒
});

架构

MCP服务器：

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

要求

• Node.js >= 18.0.0
• 一个可以连接的Minecraft服务器（Java版）
• 一个兼容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问题跟踪器。

测试

要使用Anthropic MPC检查器进行测试

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