JinDaGe - minecraft-bedrock-mcp-server MCP Details

article

README

🚀 Minecraft基岩版MCP服务器

这是一个基于TypeScript的MCP（模型上下文协议）服务器，它能通过WebSocket连接提供控制Minecraft基岩版的工具。

🚀 快速开始

前提条件

Node.js 16+
开启作弊功能的Minecraft基岩版
MCP客户端（例如：Claude Desktop、Continue等）

安装

克隆仓库

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

安装依赖

npm install

构建项目

npm run build

启动服务器

npm start

Minecraft连接

启动MCP服务器

npm start

默认端口：8001

准备Minecraft世界
- 创建或选择一个开启作弊功能的世界
- 禁用所有实验性特性
- 建议使用创造模式
从Minecraft进行连接 在Minecraft基岩版的聊天框中输入：

/connect localhost:8001/ws

验证连接 你应该能在MCP服务器的控制台看到连接日志。

MCP客户端设置（例如：Claude Desktop）

该服务器实现了MCP（模型上下文协议）标准，可与任何兼容的MCP客户端配合使用。

示例：Claude Desktop配置

找到配置文件：
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
添加服务器配置：

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

自定义端口配置：

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

重启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/             # 建筑工具

🤝 贡献指南

分叉仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

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

🙏 致谢

MCP协议提供协议规范
Sandertv/mcwss 提供WebSocket协议分析和消息结构参考

⚠️ 重要提示

Minecraft基岩版需开启作弊功能
世界设置需启用WebSocket连接
世界需具备适当权限以执行命令

🔧 故障排除

连接问题

服务器无法启动：

确保已安装Node.js 16+
检查端口8001是否已被占用：netstat -ano | findstr :8001
尝试使用 --port=8002 指定不同端口

Minecraft连接失败：

验证世界设置：
- 必须开启作弊功能
- 禁用所有实验性特性
- 使用创造模式
检查连接命令：
```
/connect localhost:8001/ws
```
防火墙设置：
- 确保端口8001允许通过Windows Defender
- 检查杀毒软件是否阻止了连接

MCP客户端集成问题：

验证配置文件路径和语法（例如：Claude Desktop）
完全重启MCP客户端
检查服务器日志中的MCP协议错误
确保配置中的文件路径为绝对路径

常见错误信息

EADDRINUSE：端口已被占用 - 尝试使用不同端口
Connection refused：服务器未运行或端口错误
unknown message purpose ws:encrypt：连接设置期间正常现象

minecraft-bedrock-mcp-server