MCP Server mod

MCP Server mod

一个Fabric模组,实现了模型上下文协议(MCP)服务器,使Claude等AI助手能够通过结构化命令与Minecraft交互。

技术

🤖 MCP Server Mod

通过将 AI 助手直接连接到游戏,彻底改变你的 Minecraft 体验!

MCP Server Mod 实现了 Model Context Protocol (MCP) 标准,创建一个可流式传输的 HTTP 服务器,让 Claude、GPT 等大型语言模型及其他 AI 助手能够通过结构化命令与你的 Minecraft 世界交互。

✨ 本模组的功能

本模组在 8080 端口运行一个可流式传输的 HTTP 服务器,接受 MCP 协议请求,使 AI 助手能够:

  • 🏗️ 建造结构:通过执行放置命令
  • 🔍 分析你的世界:通过扫描方块区域
  • 📊 获取玩家信息:包括位置、生命值和物品栏
  • 🎮 控制游戏机制:通过安全的命令执行

🛠️ 可用工具

1. execute_commands - 命令执行

在全面的安全校验下执行 Minecraft 命令:

  • 支持的命令:fill、setblock、clone、summon、tp、give、gamemode、effect、enchant、weather、time、say
  • 安全限制:防止大规模击杀实体或过度区域修改等破坏性操作
  • 结果追踪:返回方块变化、实体生成和命令结果的详细信息

2. get_player_info - 全面的玩家状态

获取玩家的详细信息:

  • 位置:精确坐标(x, y, z)和方块位置
  • 朝向:面向方向、yaw/pitch、基本方位
  • 计算位置:面向建造位置(前方 3 格)
  • 生命与状态:生命值、饥饿值、经验
  • 游戏状态:当前维度、世界时间、游戏模式
  • 物品栏:选中的槽位、主手/副手物品

适用于:上下文感知建造、相对于玩家的命令、状态监控

3. get_blocks_in_area - 世界分析

扫描矩形区域以分析结构:

  • 方块检测:返回指定区域内所有非空气方块
  • 区域限制:可配置的最大区域大小(默认:50x50x50)
  • 结构分析:非常适合理解现有建筑
  • 建造规划:在施工前检查区域

4. take_screenshot - 视觉检查

将当前 Minecraft 游戏画面捕获为 MCP 图像响应。

  • 可选的相机定位:提供 x、y、z 以在捕获前传送
  • 可选的视角控制:提供 yaw、pitch 以设置相机方向
  • 图像输出:返回 Base64 PNG(image/png)供 AI 直接分析
  • 非常适合建造质量检查:以视觉方式验证结构形状、方块放置和周围环境
  • 从版本 1.1.1+mc1.21.11 起支持

重要行为:

  • 如果提供了 x、y、z,玩家将被传送。
  • 如果提供了 yaw、pitch,玩家视角将被改变。

🚀 如何使用

安装

  1. 为 Minecraft 1.21.4 安装 Fabric Loader 0.16.14+
  2. 安装 Fabric API 0.119.3+1.21.4
  3. 将此模组放入你的 mods 文件夹
  4. 启动 Minecraft - MCP 服务器会自动在 http://localhost:8080/mcp 启动

⚠️ 重要:命令权限

在使用 AI 命令工具之前,必须允许命令输入:

  • 单人游戏:创建世界时,将 Allow Cheats(允许作弊)设置为 ON(开启)
  • 多人游戏 / 专用服务器:玩家必须拥有命令权限(OP 或等效的服务器权限)

⚠️ 重要:禁用"Pause on Lost Focus"(失焦暂停)

关键步骤:你必须禁用 Minecraft 的"Pause on Lost Focus"设置,以便在切换应用程序时允许 AI 交互:

  • 在游戏中按 F3 + P 切换关闭"Pause on Lost Focus"
  • 你会看到一条确认设置更改的消息

如果不做此更改,每次切换到你的 AI 编辑器时游戏都会暂停,导致命令无法正常执行。

连接 AI 代码编辑器(直接支持)

Cursor IDE

  1. 在 Cursor 设置中添加 MCP 服务器配置
  2. 使用 HTTP 传输:http://localhost:8080/mcp
  3. 开始使用能够控制 Minecraft 的 AI 辅助进行编码!
{
  "mcpServers": {
    "minecraft": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Windsurf IDE

  1. 在 Windsurf 中配置 MCP 连接
  2. 连接到:http://localhost:8080/mcp
  3. 启用 AI 驱动的 Minecraft 交互

带扩展的 VS Code

  • GitHub Copilot:配置 MCP 集成
  • Roo Code:直接 HTTP MCP 支持
  • 其他 MCP 扩展:兼容可流式传输的 HTTP 传输

连接其他 AI 助手

Claude Code

由于 Claude Code 使用 stdio 传输,你需要一个代理:

  1. 安装 mcp-proxy 或类似的 stdio 到 HTTP 桥接工具
  2. 配置代理以转换 stdio ↔ 可流式传输的 HTTP
  3. 将 Claude Code 连接到代理

AI 交互示例

"Build me a small house"(给我建一座小房子) → AI 使用 get_player_info 找到你的位置,然后使用 execute_commands 放置方块

"What blocks are around me?"(我周围有哪些方块?)→ AI 使用 get_blocks_in_area 扫描附近区域并报告结果

"Clear this area and build a farm"(清理此区域并建造一个农场) → AI 组合多个工具进行分析、清理和建造

🔧 技术细节

  • 可流式传输的 HTTP 传输:通过 HTTP 完整支持 MCP 协议
  • 客户端模组:完全在 Minecraft 客户端中运行
  • 符合标准:实现官方的 Model Context Protocol 规范
  • 方块压缩:自动优化方块变化的表示
  • 聊天捕获:监控命令输出和游戏响应
  • 分离环境:使用 Fabric 的客户端/主源代码分离
  • 全面的日志记录:详细的操作用于调试

🆘 故障排除

服务器无法启动?

  • 检查 8080 端口是否可用
  • 验证是否安装了 Fabric API
  • 检查日志以查找配置错误

AI 无法连接?

  • 确保防火墙允许 localhost:8080
  • 验证 MCP 客户端支持 HTTP 传输
  • 对于 stdio 客户端,使用 mcp-proxy 桥接

命令不工作?

  • 验证你拥有适当的权限
  • 检查"Pause on Lost Focus"已禁用(F3+P)
  • 检查命令语法和限制

游戏不断暂停?

  • 确保"Pause on Lost Focus"已关闭(F3+P)
  • 这对于多任务处理时的 AI 交互至关重要

🔗 链接