Minecraft MCP Http

🚀 基础实验室/Minecraft客户端

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

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

🚀 快速开始

本客户端库可助力你轻松实现与Minecraft服务器的交互，完成游戏内的各类操作。下面为你详细介绍使用前的安装步骤及使用方法。

✨ 主要特性

• 全面的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客户端集成

服务器使用标准输入输出传输方式，可与任何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（可选）：如果为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客户端集成后，你可以像这样控制机器人：

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

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

// 制作木板
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服务器：

• 使用标准输入输出传输方式与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版本。

技能无法正常工作

• 确保在使用技能之前机器人已成功生成。
• 某些技能需要特定的物品或条件。
• 检查机器人的控制台输出以查看错误消息。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🛠️ 支持

如有问题或功能请求，请使用GitHub问题跟踪器。

测试

要使用Anthropic MPC检查器进行测试，请运行：

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