Minecraft Bedrock MCP Server

🚀 Minecraft基岩版MCP服務器

這是一個基於TypeScript的MCP（模型上下文協議）服務器，它提供了通過WebSocket連接來控制Minecraft基岩版的工具。

🚀 快速開始

前提條件

• Node.js 16+
• 開啟作弊功能的Minecraft基岩版
• MCP客戶端（例如：Claude Desktop、Continue等）

安裝

1. 克隆倉庫

git clone https://github.com/Mming-Lab/minecraft-bedrock-mcp-server.git
cd minecraft-bedrock-mcp-server

2. 安裝依賴

npm install

3. 構建項目

npm run build

4. 啟動服務器

npm start

Minecraft連接

1. 啟動MCP服務器

npm start

默認端口：8001

2. 準備Minecraft世界

   • 創建或選擇一個開啟作弊功能的世界
   • 禁用所有實驗性特性
   • 建議使用創造模式

3. 從Minecraft進行連接 在Minecraft基岩版的聊天框中運行：

/connect localhost:8001/ws

4. 驗證連接 你應該能在MCP服務器控制檯看到連接日誌。

MCP客戶端設置（例如：Claude Desktop）

該服務器實現了MCP（模型上下文協議）標準，可與任何兼容的MCP客戶端配合使用。

示例：Claude Desktop配置

1. 定位配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 添加服務器配置：

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

3. 自定義端口配置：

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

4. 重啟MCP客戶端以加載新配置 對於其他MCP客戶端，請參考其各自的文檔進行服務器註冊。

✨ 主要特性

• 13個強大工具，採用分層系統組織
• 一級基礎工具：玩家控制、代理（@c）操作、世界操作
• 二級高級工具：複雜建築操作、高級世界管理
• MCP客戶端集成（例如Claude Desktop），用於實現由AI驅動的Minecraft自動化
• 類型安全的TypeScript實現，具備全面的錯誤處理

📦 安裝指南

克隆倉庫

git clone https://github.com/Mming-Lab/minecraft-bedrock-mcp-server.git
cd minecraft-bedrock-mcp-server

安裝依賴

npm install

構建項目

npm run build

啟動服務器

npm start

💻 使用示例

基礎用法

# 啟動服務器
npm start

高級用法

# 自定義端口配置
{
  "mcpServers": {
    "minecraft-bedrock-mcp-server": {
      "command": "node",
      "args": ["path/to/dist/server.js", "--port=8002"]
    }
  }
}

📚 詳細文檔

為貢獻者和開發者提供了全面的文檔。如需詳細的設置指南和架構文檔，請聯繫維護人員。

🔧 技術細節

可用腳本

npm run build    # 將TypeScript編譯為JavaScript
npm start        # 啟動編譯後的服務器
npm run dev      # 一鍵構建並啟動

端口配置

服務器端口可以通過命令行參數進行配置：

• --port=8002 - 設置自定義端口
• 默認：8001

項目結構

src/
├── server.ts              # 主服務器實現
├── types.ts               # TypeScript類型定義
└── tools/                 # 工具實現
    ├── base/tool.ts       # 抽象基類
    ├── player/            # 玩家控制工具
    ├── agent/             # 代理控制工具
    ├── world/             # 世界操作工具
    └── build/             # 建築工具

📄 許可證

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

🤝 貢獻指南

1. Fork倉庫
2. 創建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打開拉取請求

🙏 致謝

• MCP協議 提供規範
• Sandertv/mcwss 提供WebSocket協議分析和消息結構參考

⚠️ 要求

• Minecraft基岩版 開啟作弊功能
• 世界設置中啟用WebSocket連接
• 具有適當權限的世界 以執行命令

🔧 故障排除

連接問題

服務器無法啟動：

• 確保安裝了Node.js 16+
• 檢查端口8001是否已被使用：netstat -ano | findstr :8001
• 嘗試使用--port=8002指定不同的端口

Minecraft連接失敗：

1. 驗證世界設置：
   • 必須開啟作弊功能
   • 禁用所有實驗性特性
   • 使用創造模式
2. 檢查連接命令：

   /connect localhost:8001/ws
   

3. 防火牆設置：
   • 確保端口8001允許通過Windows Defender
   • 檢查防病毒軟件是否阻止了連接

MCP客戶端集成問題：

1. 驗證配置文件路徑和語法（例如：Claude Desktop）
2. 完全重啟MCP客戶端
3. 檢查服務器日誌中的MCP協議錯誤
4. 確保配置中的文件路徑為絕對路徑

常見錯誤消息

• EADDRINUSE：端口已被使用 - 嘗試使用不同的端口
• Connection refused：服務器未運行或端口錯誤
• unknown message purpose ws:encrypt：連接設置期間正常現象

🛠️ 可用工具

玩家控制

• player_position - 獲取玩家當前位置
• player_move - 將玩家移動/傳送至指定座標
• player_say - 以玩家身份發送消息

代理控制（教育版）

• agent_move - 向指定方向或座標移動代理 ✅
• agent_turn - 向左/右轉動代理或設置特定旋轉角度 ✅
• agent_attack - ❌ 基岩版不支持
• agent_block_action - ❌ 基岩版不支持

世界操作

• world_block - 世界方塊操作（設置、獲取、破壞）
• world_fill - 使用高級選項填充區域
• world_time_weather - 控制時間和天氣

建築工具

• build_cube - 建造實心或空心立方體
• build_line - 在點之間建造直線
• build_sphere - 建造實心或空心球體

基本通信

• send_message - 發送聊天消息
• execute_command - 執行任何Minecraft命令