Minecraft MCP Http

🚀 Fundamental Labs/Minecraft客戶端

本庫是用於Minecraft遊戲技能和MCP集成的客戶端庫。Fairies MCP客戶端（https://fairies.ai/）也支持一鍵直接連接。

🚀 快速開始

本庫可幫助你將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

命令行選項

Options:
  -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（可選）：如果為 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服務器：

• 使用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版本。

技能無法正常工作

• 確保在使用技能之前機器人已成功生成。
• 某些技能需要特定的物品或條件。
• 檢查機器人的控制檯輸出以查看錯誤消息。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

支持

如有問題或功能請求，請使用 GitHub問題跟蹤器。

測試

要使用Anthropic MPC檢查器進行測試，請運行：

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