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實現，具備全面的錯誤處理

🛠️ 可用工具

玩家控制

• 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命令

📚 詳細文檔

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

💻 使用示例

基礎用法

# 克隆倉庫
git clone https://github.com/Mming-Lab/minecraft-bedrock-mcp-server.git
cd minecraft-bedrock-mcp-server

# 安裝依賴
npm install

# 構建項目
npm run build

# 啟動服務器
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/             # 建築工具

🤝 貢獻指南

1. 分叉倉庫
2. 創建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打開拉取請求

📄 許可證

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

🙏 致謝

• 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：連接設置期間正常現象