MCP Server Mod

Minecraft MCP服务器模块

一个实现模型上下文协议（MCP）服务器的Fabric mod，使像克劳德这样的人工智能助手能够通过结构化命令与Minecraft进行交互。

概述

该模块在Minecraft客户端或专用服务器中创建一个HTTP服务器，接受MCP协议请求，允许大型语言模型安全有效地执行Minecraft命令。该模块包括全面的安全验证，以防止破坏性操作。

它被设计为与单人（集成服务器）和多人专用服务器完全兼容。

特性

• 服务器和客户端支持：适用于单人和专用服务器环境。
• MCP协议支持：全面实施AI交互的模型上下文协议
• 安全确认：全面的命令过滤和验证系统
• 异步执行：执行非阻塞命令以保持游戏性能
• 可配置设置：可自定义的安全限制、服务器设置和命令权限
• 实时反馈：详细的执行结果，包括块计数和实体信息

需求

• 我的世界: 1.21.11
• 织物装载机：0.18.4或更高
• 结构API：0.141.3+1.21.11或更高
• Java：21或以上

安装

1. 安装 织物装载机 适用于《我的世界》1.21.11
2. 下载并安装 结构API
3. 将mod JAR文件放入您的 mods 文件夹
4. 使用Fabric配置文件启动Minecraft

用法

启动MCP服务器

当您启动安装了mod的Minecraft时，MCP服务器会自动启动。默认情况下，它运行在 localhost:8080.

服务器模式与客户端模式

mod检测它是在客户端（单人）还是专用服务器环境中运行：

• 客户端模式：全功能支持，包括 take_screenshot 该工具使用本地游戏窗口。
• 专用服务器模式：可以使用以下工具 execute_commands, get_player_info，以及 get_blocks_in_area，无需渲染即可对世界进行完全的人工智能操纵 take_screenshot 由于没有呈现上下文，该工具在服务器模式下被禁用。请注意 get_player_info 当前选择服务器上的第一个在线玩家来报告其位置。

如果玩单人游戏，集成服务器逻辑将通过客户端MCP运行。

配置

mod在以下位置创建配置文件 config/mcp.json:

{
  "server": {
    "port": 8080,
    "host": "localhost",
    "enable_safety": true,
    "max_area_size": 50,
    "allowed_commands": ["fill", "clone", "setblock", "summon", "tp", "give"],
    "request_timeout_ms": 30000
  },
  "client": {
    "auto_start": true,
    "show_notifications": true,
    "log_level": "INFO",
    "log_commands": false,
    "save_screenshots_for_debug": false
  },
  "safety": {
    "max_entities_per_command": 10,
    "max_blocks_per_command": 125000,
    "block_creative_for_all": true,
    "require_op_for_admin_commands": true
  }
}

server.request_timeout_ms 限制服务器等待工具执行的时间（包括 execute_commands 和 take_screenshot)在返回超时错误之前。

与AI助手连接

使用端点将您的AI助手（如Claude）连接到MCP服务器：

http://localhost:8080/mcp

服务器支持三个主要工具：

• execute_commands -执行Minecraft命令并进行安全验证
• get_player_info -获取全面的玩家信息
• get_blocks_in_area -扫描并检索指定区域中的块
• take_screenshot -使用可选的相机控制捕捉游戏屏幕

示例命令

AI可以执行以下命令：

• fill ~ ~ ~ ~10 ~5 ~8 oak_planks -用方块填充一个区域
• summon villager ~ ~ ~ -生成实体
• setblock ~ ~1 ~ oak_door -放置特定块
• tp @s ~ ~10 ~ -Teleport播放器
• give @s diamond_sword -赠送物品

安全特性

允许的命令

• 建筑： fill, clone, setblock
• 实体： summon, tp, teleport
• 项目： give
• 游戏状态： gamemode, effect, enchant, weather, time
• 沟通： say, tell, title

受阻操作

• 大规模实体破坏(kill @a, kill @e)
• 过大面积作业（>50×50×50块）
• 批量项目生成（>100个项目）
• 全球创意模式分配

发展

建筑

./gradlew build

在发展中奔跑

./gradlew runClient

项目结构

src/
├── main/java/cuspymd/mcp/mod/
│   ├── MCPServerMod.java           # Main mod class
│   ├── MCPServerModClient.java     # Client initializer
│   ├── server/                     # MCP server implementation
│   ├── command/                    # Command execution system
│   ├── config/                     # Configuration management
│   └── utils/                      # Utility classes
└── main/resources/
    ├── fabric.mod.json             # Mod metadata
    └── *.mixins.json              # Mixin configurations

API 参考

MCP端点

• POST /mcp/initialize -初始化MCP会话
• POST /mcp/ping -健康检查
• POST /mcp/tools/list -列出可用工具
• POST /mcp/tools/call -执行命令

工具：执行_命令

按顺序执行一个或多个Minecraft命令，并进行安全验证。

参数：

• commands （array）：Minecraft命令列表（不带前导斜线）
• validate_safety （boolean）：启用安全验证（默认值：true）

响应模式（文本有效载荷JSON）：

• 顶层： totalCommands, acceptedCount, appliedCount, failedCount, results, chatMessages
• 根据命令： index, command, status, accepted, applied, summary, chatMessages
• status 值： applied, rejected_by_game, execution_error, timed_out, rejected_by_safety, unknown

请求示例：

{
  "method": "tools/call",
  "params": {
    "name": "execute_commands",
    "arguments": {
      "commands": [
        "fill ~ ~ ~ ~10 ~5 ~8 oak_planks",
        "setblock ~5 ~6 ~4 oak_door"
      ],
      "validate_safety": true
    }
  }
}

工具：get_player_info

获取全面的玩家信息，包括位置、朝向、健康状况、库存和游戏状态。

参数： 无需

答复包括：

• 精确位置（x、y、z坐标）和块坐标
• 朝向（偏航、俯仰、主方向）
• 建筑物的计算前部位置（前方3个街区）
• 查找矢量进行方向计算
• 健康、食物和体验状况
• 当前游戏模式和维度
• 世界时间信息
• 库存详细信息（所选插槽、主要/现成物品）

请求示例：

{
  "method": "tools/call",
  "params": {
    "name": "get_player_info",
    "arguments": {}
  }
}

工具：get_blocks_in_area

扫描并检索指定矩形区域内的所有非空气块。可用于分析结构或检查构建区域。

参数：

• from （对象）：以x、y、z坐标为起始位置
• to （对象）：以x、y、z坐标表示的结束位置

答复包括：

• 该区域所有非空气块清单
• 块类型和位置
• 总块数
• 区域尺寸和验证信息

请求示例：

{
  "method": "tools/call", 
  "params": {
    "name": "get_blocks_in_area",
    "arguments": {
      "from": {"x": 100, "y": 64, "z": 200},
      "to": {"x": 110, "y": 74, "z": 210}
    }
  }
}

注： 每个轴的最大区域大小受服务器配置的限制（默认值：50个块）。

工具：take_screenshot

捕捉当前Minecraft游戏屏幕的屏幕截图。您可以选择指定坐标和旋转来移动玩家，并在截图前设置他们的视线。

参数：

• x （数字，可选）：将玩家传送到的X坐标。
• y （数字，可选）：将玩家传送到的Y坐标。
• z （数字，可选）：将玩家传送到的Z坐标。
• yaw （数字，可选）：横摆旋转（0-360）用于水平视图。
• pitch （数字，可选）：俯仰旋转（-90至90）用于垂直视图。

答复包括：

• Base64编码的PNG图像数据。
• MIME类型(image/png).

请求示例：

{
  "method": "tools/call",
  "params": {
    "name": "take_screenshot",
    "arguments": {
      "x": 120.5,
      "y": 70,
      "z": -200.5,
      "yaw": 180,
      "pitch": 0
    }
  }
}

调试

本地截图存储

出于调试目的，您可以启用MCP服务器捕获的每个屏幕截图的本地保存。

1. 打开 config/mcp.json.
2. 集 "save_screenshots_for_debug": true 在 client 部分。
3. 屏幕截图将保存到 mcp_debug_screenshots/ Minecraft实例文件夹中的目录。
4. 文件使用以下模式命名： screenshot_YYYYMMDD_HHMMSS_SSS.png.

许可证

本项目根据CC0-1.0许可证获得许可。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试（参见 测试.md 了解更多信息）
5. 提交拉取请求

支持

对于问题和疑问：

• 检查 问题 页
• 查看配置文档
• 启用调试日志记录以进行详细的故障排除