AI导哈

Minecraft生存MCP服务器

一个基于TypeScript的Minecraft生存模式MCP服务器，专为LLM代理设计，提供自动化的游戏操作和环境交互功能。

  • by Netherite-Stack
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Netherite-Stack/Minecraft-Survival-MCP-Server

使用说明

Minecraft生存MCP服务器

Minecraft Survival的TypeScript模型上下文协议（MCP）服务器，由 Mineflayer。此服务器是专门为允许LLM代理在Minecraft中玩游戏和生存而设计的。

愿景：螺旋方法

该项目的灵感来自 图AI的螺旋虽然现有的实现方式类似 yuniko软件/minecraft mcp服务器 提供一套全面的低级工具， mc-mcp 旨在将“琐碎”执行的负担从LLM转移出去。

  • 心灵（LLM）： 专注于高层意图、战略和长期目标。
  • 主体（MCP服务器）： 处理“事务”——自主寻路、几何数学、逐块构造逻辑和环境处理。

目标是防止LLM陷入坐标算法或单个工具选择，使其能够作为一个纯粹的认知层。

快速开始

安装

npm install
npm run build

截图依赖关系（可选）

这 capture_bot_view 工具需求 node-canvas-webgl.

在安装之前使用Node 24 LTS（或22 LTS）：

nvm install 24
nvm use 24
npm install github:PrismarineJS/node-canvas-webgl

螺旋方法和关键改进

传统的Minecraft MCP实现通常将LLM视为“低级控制器”。由于LLM在3D坐标数学或逐步块放置方面遇到困难，这会导致高延迟、令牌浪费和频繁故障。

mc-mcp 通过实现“事务体”架构来翻转此模型：

1.意图与执行（身心分裂）

LLM没有要求LLM“前进，然后左转，然后跳”，而是简单地说“去[X，Y，Z]的村庄。”MCP服务器（Body）自主处理A*寻路、避障和物理计算。

2.交易操作

复杂的任务被暴露为单个高级事务。

  • 当前： get_own_position, move_to_coordinates, move_to_player, open_door_or_trapdoor, close_door_or_trapdoor, mine_block_by_coords, mine_room, break_tree, mine_stairs, place_block_at, place_wall, place_ceiling, get_inventory_contents, get_inventory_status, drop_inventory_item, put_item_in_chest, take_item_from_chest, get_chest_contents, get_chest_status, craft_item, smelt_item, capture_bot_view, get_biome_info, get_daytime_info, sleep_in_bed, locate_blocks_in_area, locate_dropped_items, search_blocks_wiki, search_items_wiki, get_crafting_recipe, list_players, find_player, get_player_coordinates, distance_to_player, find_nearest_players.
  • 计划： build_structure （服务器处理的几何模板）， harvest_area （区域扫描和路径优化）。

3.减少认知负荷

通过抽象“如何”，LLM有更多的上下文窗口可用于“为什么”——允许更复杂的推理、多智能体协调和创造性的问题解决，而不会被Minecraft的技术限制分心。

4.容器优先架构

设计用于在隔离环境（Docker/GHCR）中运行，使部署可由集中式智能控制的“工蜂”变得容易。

开发与部署

本地开发

npm install
npm run dev

环境变量

  • MCP_TRANSPORT：设置为 remote 启用HTTP/SSE服务器（默认： stdio).
  • PORT：远程服务器的端口（默认值： 3000).
  • HOST：远程服务器的主机（默认值： 0.0.0.0).
  • MC_HOST：启动时使用的Minecraft服务器主机（默认值： localhost).
  • MC_PORT：Minecraft服务器端口（默认值： 25565).
  • MC_USERNAME：机器人用户名（默认值： MCP-Bot).
  • ENABLE_VIEWER：设置为 1/true 在bot生成后启动prismarine查看器web流（默认：禁用）。查看器页面包括一个HUD覆盖层（心形和手持物品）。
  • VIEWER_PORT：prismarine查看器的端口（默认值： 3000).
  • ENABLE_IMAGES：设置为 1/true 以便能够注册 capture_bot_view.
  • LOG_LEVEL：引脚日志级别(trace, debug, info, warn, error, fatal；默认值： info).

REST API

当 MCP_TRANSPORT=remote，还为以下REST端点提供服务 PORT 旁边 /mcp.全部返回 503 与 { "error": "Bot is not connected yet." } 如果机器人没有连接。

  • GET /api/status：机器人用户名、健康、饥饿、位置和装备盔甲。
    {
  "username": "MCP-Bot",
  "health": 20,
  "hunger": 20,
  "position": { "x": 0, "y": 64, "z": 0 },
  "armor": {
    "helmet": { "id": 869, "name": "diamond_helmet", "count": 1 },
    "chestplate": null,
    "leggings": null,
    "boots": null
  }
}
  • GET /api/inventory：包含Minecraft物品id和名称的库存内容。
    { "items": [{ "slot": 9, "id": 264, "name": "diamond", "count": 3 }] }
  • POST /api/respawn：重新启动机器人。只有在机器人死亡时才允许；回报 409 否则。注： respawn 在机器人的mineflayer配置中被禁用，所以死亡总是需要这个调用。

可用工具

运动模块

  • get_own_position：获取机器人的当前坐标。
  • move_to_coordinates：移动到目标坐标。输入： x, y, z, allow_block_breaking, allow_block_placement, timeout_ms.
  • move_to_player：靠近玩家。输入： username, range, allow_block_breaking, allow_block_placement, timeout_ms.
  • open_door_or_trapdoor：通过可选坐标或范围内最近的坐标打开门/活板门。输入：可选 x, y, z, max_distance.
  • close_door_or_trapdoor：通过可选坐标或范围内最近的坐标关闭门/活板门。输入：可选 x, y, z, max_distance.

采矿模块

  • mine_block_by_coords：通过可开采性/工具检查开采一个区块。输入： x, y, z, timeout_ms.
  • mine_room：逐层挖掘一个长方体区域。输入： start_x, start_y, start_z, length, width, depth, timeout_ms.
  • break_tree：断开所有连接的日志状块(log, stem, hyphae).输入： x, y, z, timeout_ms, allow_build_up_if_needed.
  • mine_stairs：创建一个下降楼梯隧道，达到目标深度。输入： depth, timeout_ms.

建筑模块

  • place_block_at：在支持/实体/库存检查的坐标处放置一个块。输入： block_name, x, y, z, timeout_ms.
  • place_wall：从起点坐标放置墙平面。输入： block_name, start_x, start_y, start_z, x_length, y_height, z_length，可选 x_direction, y_direction, z_direction, timeout_ms。在构建之前，会强制执行资源检查。
  • place_ceiling：从起点坐标放置天花板平面。输入： block_name, start_x, start_y, start_z, x_length, z_length，可选 x_direction, z_direction, timeout_ms。在构建之前，会强制执行资源检查。

库存模块

  • get_inventory_contents：列出带有项目名称和计数的库存项目堆栈。
  • get_inventory_status：报告库存插槽使用情况(used, free, total).
  • drop_inventory_item：按查询/名称和金额删除项目。输入： query, count。如果数量缺失或不足，则返回明显错误。
  • put_item_in_chest：将库存中的物品放在最近的箱子里。输入： query, count。如果箱子/物品丢失，则返回明显错误。
  • take_item_from_chest：从最近的箱子里取出物品放入库存。输入： query, count。如果箱子/物品丢失或不足，则返回明显错误。
  • get_chest_contents：列出最近的胸部内容物，包括物品名称和数量。
  • get_chest_status：报告最近的胸槽使用情况(used, free, total).

视觉模块

  • capture_bot_view：从机器人中捕获第一人称屏幕截图。输入： width （默认值 800), height （默认值 400), view_distance 以块为单位（默认 96), quality, look_at_x, look_at_y, look_at_z.
  • get_biome_info：获取当前或可选坐标处的生物群落信息。输入：可选 x, y, z.
  • get_daytime_info：获取白天/时间状态并滴答作响，直到睡眠窗口。
  • sleep_in_bed：根据可选坐标或范围内最近的床睡在床上。输入：可选 x, y, z, max_distance, timeout_ms.
  • locate_blocks_in_area：按名称/id/通配符查找块，按最近者排序。输入： query, radius, max_results，可选 center_x, center_y, center_z.
  • locate_dropped_items：查找已删除的项目实体，按最近的排序。输入： radius, max_results，可选 query.

Wiki模块

  • search_blocks_wiki：从Mineflayer的内置注册表中搜索块名称和ID。输入： query, max_results.
  • search_items_wiki：从Mineflayer的内置注册表中搜索项目名称和ID。输入： query, max_results.
  • get_crafting_recipe：显示项目和数量的配方成分要求，包括制作表要求。输入： item, amount.

制作模块

  • craft_item：按名称和数量制作物品。使用库存制作或附近的制作桌。失败时，返回关于缺失资源和/或制定表格要求的可操作指南。输入： item, amount.
  • smelt_item：在附近的炉状块中冶炼一件物品。故障时，返回有关丢失的炉子、燃料和/或输入资源的可操作指南。输入： item, amount，可选 fuel_query。对进度停滞使用固定的内部超时（正常Minecraft冶炼时间的2倍）。

多人游戏模块

  • list_players：获取服务器上所有当前已知的玩家。
  • find_player：按部分用户名搜索玩家（不区分大小写）。输入： query.
  • get_player_coordinates：获取可见玩家的坐标。输入： username.
  • distance_to_player：以区块为单位计算机器人到玩家的3D距离。输入： username.
  • find_nearest_players：查找最近的可见玩家。输入： x_parameter.

服务器只管理一个机器人进程，并在启动时自动尝试连接。

许可证

麻省理工学院

相关 MCP