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