Awesome Mineflayer MCP

awesome-mineflayer-mcp

一个可用于生产环境的 Model Context Protocol 服务，可让大模型 Agent 获得与独立运行时相当的控制能力，操控 Mineflayer Minecraft 机器人，涵盖移动、挖矿、制作、物品栏、战斗、容器、聊天等众多功能。它通过 26 组共 123 个强类型工具提供这些功能，另有引导式提示词、视觉（真实第一人称截图和结构示意图）、持久化航点、建造/挖掘宏，以及双通道（轮询 + 推送）事件流，并支持完整的机器人生命周期管理。工具结果同时包含人类可读文本和机器可读的 structuredContent。

基于 Mineflayer 生态：mineflayer-pathfinder（A* 导航）、mineflayer-pvp（战斗）、mineflayer-collectblock（采集）、mineflayer-tool（自动选择工具）、mineflayer-auto-eat 和 mineflayer-armor-manager。

---

要求

• Node.js ≥ 20（基于 22.16 开发）
• 一个可供连接的 Minecraft 服务器（Java 版）。机器人会自动检测服务器版本。还没有服务器？请参阅获取用于测试的服务器。
• 对于在线模式服务器：需要 Microsoft 账号（auth: "microsoft"）。

支持的版本

	支持范围
Minecraft（Java）	随附的 mineflayer 4.37 / minecraft-data 支持的范围（大致为 1.8 → 1.21.x）；版本会自动检测，也可以显式传入 version
Node.js	20、22（LTS）

少数工具仅适用于较新的版本/功能（例如 elytra_fly、聊天签名）。版本不匹配时，机器人会因 outdated client/server 消息而被踢出，请显式传入 version。

安装

使用 npx 按需运行（无需安装）：

npx awesome-mineflayer-mcp

……或全局安装：

npm install -g awesome-mineflayer-mcp
awesome-mineflayer-mcp

该服务通过 stdio 使用 MCP，因此通常由 MCP 客户端启动，而不是手动运行。

与 MCP 客户端搭配使用

将其添加到客户端的 MCP 服务配置中。推荐使用 npx，这样始终可以获取最新发布版本：

Claude Desktop（claude_desktop_config.json）、Claude Code、Cursor 或任何 stdio MCP 客户端：

{
  "mcpServers": {
    "mineflayer": {
      "command": "npx",
      "args": ["-y", "awesome-mineflayer-mcp"],
      "env": {
        "MCP_DISABLE_GROUPS": ""
      }
    }
  }
}

如果已全局安装，请改用 "command": "awesome-mineflayer-mcp" 和 "args": []。

获取用于测试的 Minecraft 服务器

如果你还没有服务器，可以使用 Docker 启动一个临时的离线模式服务器（无需账号）：

# from a clone of this repo:
docker compose up -d        # offline 1.20.4 server on localhost:25565
docker compose logs -f      # wait for "Done (…)! For help, type "help""

……也可以不克隆仓库，使用一条命令启动：

docker run -d --name mc -p 25565:25565 -e EULA=TRUE -e ONLINE_MODE=FALSE -e VERSION=1.20.4 itzg/minecraft-server

然后连接：connect_bot { host: "localhost", username: "DevBot", auth: "offline" }。使用 docker compose down -v（或 docker rm -f mc）将其关闭。不要将离线模式服务器暴露到公共互联网。

自主运行（默认账号）

如需无人值守运行，请配置一个默认账号，这样机器人会在启动时自动连接，无需调用 connect_bot。运行交互式设置：

npx awesome-mineflayer-mcp setup

设置会询问服务器主机/端口、使用离线账号还是 Microsoft 账号，以及是否在启动时自动连接，随后写入 ~/.awesome-mineflayer-mcp/config.json（不会存储密码）。使用 Microsoft 账号时，设置过程会运行一次设备代码登录，并将令牌缓存在 profilesFolder 下，因此后续启动无需提示。

启动时，服务会自动连接配置的账号（可通过 get_connection_status 确认）。Agent 也可以调用 connect_default 来连接或重新连接，或调用 get_default_account 查看账号信息。

不使用向导进行配置（环境变量）

你可以完全通过 MCP 客户端配置设置默认账户，方便在无头环境中部署。环境变量优先于配置文件：

{
  "mcpServers": {
    "mineflayer": {
      "command": "npx",
      "args": ["-y", "awesome-mineflayer-mcp"],
      "env": {
        "MCP_DEFAULT_HOST": "play.example.net",
        "MCP_DEFAULT_USERNAME": "MyBot",
        "MCP_DEFAULT_AUTH": "offline",
        "MCP_AUTO_CONNECT": "true"
      }
    }
  }
}

对于无头环境中的 Microsoft 身份验证，请先在本地运行一次 setup（或将 MCP_PROFILES_FOLDER 指向包含预缓存令牌的目录）。

配置（环境变量）

变量	默认值	用途
MCP_DISABLE_GROUPS	(none)	要禁用的工具组键，以逗号分隔（参见目录）。对于难以处理大型工具列表的客户端，可精简工具列表。
MCP_CHARACTER_LIMIT	25000	单次工具调用返回的最大字符数（超出部分会被截断并附带标记）。
MCP_EVENT_BUFFER	1000	内存事件环形缓冲区的大小。
MCP_THROTTLE_MS	250	推送资源更新／日志通知的最小间隔。
MCP_PROXIMITY_RADIUS	32	用于按距离筛选事件（实体生成、声音）的半径（方块数）。
MCP_ACTION_TIMEOUT_MS	60000	调用方未指定超时时，长时间操作的默认超时时间。
MCP_DEFAULT_HOST / MCP_DEFAULT_PORT	—	启动时自动连接的默认服务。
MCP_DEFAULT_USERNAME	—	默认账户名（离线模式）或电子邮件地址（microsoft）。
MCP_DEFAULT_AUTH	offline	默认身份验证模式：offline 或 microsoft。
MCP_DEFAULT_VERSION	auto	为默认账户强制指定协议版本。
MCP_DEFAULT_AUTO_RECONNECT	true	断开连接后自动重新连接默认账户。
MCP_AUTO_CONNECT	true†	启动时自动连接默认账户（† 仅在已配置默认账户时）。
MCP_PROFILES_FOLDER	<home>/profiles	Microsoft 身份验证令牌缓存目录。
AWESOME_MINEFLAYER_MCP_HOME	~/.awesome-mineflayer-mcp	配置和令牌缓存目录。
MCP_READ_ONLY	false	仅观察模式：只注册只读工具（以及生命周期工具）。参见安全与防护措施。
MCP_COMMAND_DENY	(admin verbs)	run_command 禁止执行的斜杠命令。设置后会替换默认值；设为空则允许所有命令。
MCP_COMMAND_ALLOW	(none)	如果设置，则使用严格的允许列表：只运行这些命令（忽略禁止列表）。
MCP_ALLOWED_HOSTS	(any)	机器人可连接的主机允许列表，以逗号分隔。
MCP_CHAT_MIN_INTERVAL_MS	0	发送聊天／悄悄话／命令的最小间隔（防止刷屏）。
MCP_ENABLE_RAW	false	启用高级／不安全的 raw 协议工具组（直接发送／订阅数据包）。
MCP_SCREENSHOT_WIDTH / _HEIGHT	800 / 450	get_screenshot 的默认图像尺寸（px）。
MCP_SCREENSHOT_LOAD_MS	2500	截图前留给世界进行渲染的时间。
MCP_VIEW_DISTANCE	4	截图的区块渲染距离。
MCP_SCREENSHOT_BROWSER_CHANNEL	(auto)	截图使用的浏览器通道（chrome、msedge、chromium）。
MCP_SCREENSHOT_EXECUTABLE_PATH	(none)	截图使用的浏览器可执行文件路径（覆盖通道设置）。

示例 — 禁用不常用的工具组：

MCP_DISABLE_GROUPS=creative,villager,enchanting,settings

快速开始（工具流程）

1. connect_bot { host, username, auth } — 连接（机器人生成后即完成）。如果已配置默认账户，则跳过此步骤 — 机器人会在启动时自动连接；只需检查 get_connection_status。
2. 执行操作：goto、dig、collect_block、craft_item、pvp_attack、chat，……
3. 观察：调用 get_observation 获取一次性快照（生命值、位置、库存、附近实体、新事件）— 每个 tick 都传入返回的 events.nextSince。或者组合使用 get_state / get_inventory / list_entities / get_events，或订阅 bot://* 资源。
4. 完成后调用 disconnect_bot。

刚接触服务器？使用 getting_started 提示词（参见提示词）获取上下文内的操作指南。

方块 / 物品 / 实体参数接受人类可读名称（"iron_ore"、"diamond_pickaxe"、"zombie"）；未知名称会返回模糊匹配建议。

身份验证

• auth: "offline"（默认）— 离线模式服务器；username 是游戏内名称。
• auth: "microsoft" — username 是账户邮箱。设备代码提示会作为 msa_code 事件 / 日志通知发出。设置 profilesFolder 以缓存令牌，让后续运行跳过提示；也可以传入缓存的 accessToken。**提示：**运行一次 npx awesome-mineflayer-mcp setup，完成设备代码登录并缓存令牌，之后服务器便会自主连接（参见自主运行）。

---

工具目录（123 个工具，26 个分组）

完整的生成式参考（包含每个工具、提示词和资源）：docs/TOOLS.md。

分组键（用于 MCP_DISABLE_GROUPS）显示在方括号中。

• 生命周期 [lifecycle] — connect_bot、connect_default、disconnect_bot、reconnect_bot、respawn、get_connection_status、get_default_account
• 状态与检查 [state]（只读）— get_observation（为 Agent 的观察循环提供单次调用快照）、get_state、get_inventory、list_players、list_entities、find_nearest_entity、get_entity_details、get_scoreboards、get_teams、get_boss_bars、get_control_states、get_chat_patterns、support_feature、pathfinder_status、get_settings、get_physics、get_loaded_plugins
• 世界查询 [world]（只读）— get_block_at、find_blocks、get_cursor_target、get_blocks_in_region、wait_for_chunks_to_load
• 移动与寻路 [movement] — goto、set_goal、flee_from、follow_entity、stop_pathfinding、get_path_to、configure_movements、configure_pathfinder、set_control_state、clear_control_states、elytra_fly、wait_for_ticks、set_physics_enabled
• 视线 [look] — look_at、look、look_at_entity
• 挖掘与建造 [digging] — dig、place_block、activate_block、activate_entity、swing_arm
• 战斗 [combat] — pvp_attack、attack_entity、pvp_stop、pvp_configure
• 物品栏与物品 [inventory] — equip_item、unequip_item、toss_item、set_quickbar_slot、consume、activate_item、click_window、move_slot_item、transfer_items
• 容器 [containers] — open_container、read_open_container、container_deposit、container_withdraw、close_window
• 熔炉 / 冶炼 [furnace] — open_furnace、furnace_action、furnace_status、smelt_item
• 附魔与铁砧 [enchanting] — enchant_item、anvil_combine
• 村民交易 [villager] — open_villager、trade_with_villager
• 合成 [crafting] — list_recipes、craft_item
• 方块采集 [gathering] — collect_block、cancel_collect、set_collect_config
• 工具自动选择 [tool] — equip_tool_for_block、set_tool_chest_locations、get_best_tool
• 生存自动化 [survival] — autoeat_set_enabled、autoeat_configure、autoeat_eat、autoeat_cancel、autoeat_preview、armor_equip_all
• 床与睡眠 [beds] — sleep、wake
• 载具 [vehicles] — mount_entity、dismount、steer_vehicle
• 钓鱼、书籍与告示牌 [fishing] — fish、cancel_fish、write_book、update_sign
• 聊天与通信 [chat] — chat、whisper、run_command、tab_complete、register_chat_pattern、remove_chat_pattern、wait_for_message
• 设置 [settings] — set_settings
• 创造模式 [creative] — creative_set_inventory_slot、creative_clear_inventory、creative_fly、creative_fly_to
• 视觉 [vision] — get_screenshot（真实的第一人称纹理游戏画面）、render_map（无需依赖项的示意地图）— 参见 视觉
• 航点 [waypoints] — set_waypoint、list_waypoints、delete_waypoint、goto_waypoint（重启后仍会保留）
• 建造与挖掘宏 [build] — clear_region、dig_tunnel、dig_staircase、fill_region（支持取消，可处理多个方块）
• 事件与遥测 [events] — get_events、cancel_task
• 原始协议 [raw] — send_packet、subscribe_packet、list_packet_subscriptions（高级 / 不安全；除非设置 MCP_ENABLE_RAW=true，否则默认关闭）

长时间运行的操作（goto、dig、collect_block、pvp_attack、fish、smelt_item、craft_item）彼此互斥且可取消——启动新的移动 / 战斗操作可取代之前的操作；也可以调用 stop_pathfinding / pvp_stop / cancel_collect / cancel_fish / cancel_task。

提示词

服务器将有引导、可参数化的工作流作为 MCP 提示词公开，客户端会将其显示为斜杠命令／模板。它们会教 Agent 如何串联合适的工具来实现目标：

• getting_started — 入门指引：连接 → 观察 → 行动 → 恢复。
• gather_wood { count?, logType? } — 寻找树木并收集原木。
• mine_to_diamonds { targetY? } — 安全下矿并开采支矿道。
• build_shelter { material? } — 在夜幕降临前围出安全空间。
• find_and_smelt { input, fuel? } — 开采／收集原料并进行熔炼。
• follow_and_defend { player } — 跟随玩家并击退敌对生物。

方块／物品参数支持自动补全，选项取自已连接的世界。

视觉 — 让 Agent 看见

两个互补的工具会以 MCP 图像内容的形式返回 PNG 图片，让具备视觉能力的模型（以及人类）直接查看世界，而不必从 JSON 中还原场景。

get_screenshot — 真实的游戏画面

捕获机器人所见的实际 Minecraft 贴图渲染画面——默认从机器人视角进行第一人称拍摄，也可选择第三人称环绕视角，效果与游戏内截图完全相同。底层使用 prismarine-viewer 渲染真实世界（客户端 WebGL），再由无头浏览器截图。参数：width、height、firstPerson、waitMs、viewDistance。

设置（仅需一次）。 渲染器依赖作为可选软件包提供（运行 npm install 时默认安装）。此外，你只需要一个浏览器：

• 已有 Google Chrome 或 Microsoft Edge？无需操作——程序会自动使用。
• 否则，运行一次 npx playwright install chromium。
• 无头服务器：安装 Chrome/Chromium，或设置 MCP_SCREENSHOT_EXECUTABLE_PATH / MCP_SCREENSHOT_BROWSER_CHANNEL。

如果依赖项／浏览器不可用，get_screenshot 会返回清晰的 UNSUPPORTED 错误，并提供上述步骤；服务器的其他功能不受影响。渲染器软件包为纯 JS（无需原生编译），但如果你希望安装内容尽可能精简且不需要截图，可使用 npm install --omit=optional。

render_map — 无依赖的示意图

基于方块数据绘制的轻量级彩色俯视地图（或 mode:"slice" 剖面图），使用内置 PNG 编码器（完全无需额外依赖）。适合用作小地图／概览，也适用于未安装截图扩展的情况。北方（−Z）朝上；机器人以带朝向标记的白点表示；玩家为青色，敌对生物为红色，被动生物为黄色，物品为灰色；包含方块图例。

安全与防护措施

在 Agent 自主驱动机器人时（尤其是使用默认账户时），一些合理的默认设置会很重要：

• 命令策略。 run_command 默认会拦截服务器管理类动词（op、deop、ban、kick、stop、whitelist，以及 execute/function/schedule 包装命令等）。普通游戏命令（/tp、/time、/give 等）则允许使用。可通过 MCP_COMMAND_DENY 覆盖（替换默认值；设为空表示全部允许），或通过 MCP_COMMAND_ALLOW 锁定允许列表（严格白名单）。这只是尽力而为的纵深防御，并非硬性边界——它仅检查第一个命令动词，而拥有管理员权限的机器人仍可能找到绕过方法。对于不可信或自主运行的部署，建议使用 MCP_COMMAND_ALLOW、MCP_READ_ONLY，并且不要授予机器人账户管理员权限。**注意：**玩家聊天消息会以事件形式发送给你的 Agent——请将其视为不可信输入。
• 主机允许列表。 MCP_ALLOWED_HOSTS 会限制 connect_bot / reconnect_bot 可以加入的服务器，防止 Agent 将机器人（及其缓存令牌）重定向到任意地址。
• 只读模式。 MCP_READ_ONLY=true 只会注册观察类工具（以及连接管理工具）——只看不动。
• 速率限制。 MCP_CHAT_MIN_INTERVAL_MS 会拉开外发聊天消息/命令的间隔，避免因刷屏被踢出。
• 不会泄露机密信息。 密码/访问令牌绝不会存储在磁盘上，并且会从连接错误消息中删除。

资源

支持资源订阅的客户端可订阅以下 JSON 资源：

• bot://state — 实时自身快照（位置、生命值、游戏模式、时间、天气、手持物品、控制状态）
• bot://inventory — 物品、盔甲、副手物品、手持栏位
• world://entities — 距离最近的最多 50 个已追踪实体
• world://players — 服务器玩家列表
• bot://events — 最近事件记录
• bot://waypoints — 已保存的命名航点

此外，还有用于按需查询的参数化资源模板：block://{x}/{y}/{z} 和 entity://{id}。

事件

游戏事件通过两种方式发送：

• 拉取：get_events({ since, types, limit }) 会读取并清空环形缓冲区；传入返回的 nextSince 即可仅读取新事件。若自 since 以来缓冲区已溢出，dropped: true 会发出提示。
• **推送：**已订阅的资源会发送节流后的 notifications/resources/updated；值得注意的日志行（聊天、死亡、踢出、错误、msa_code）会通过 sendLoggingMessage 转发。

高频观察数据（移动、每 tick 更新、方块/实体更新、时间）有意不进行缓冲——请通过 get_state 和只读工具按需读取。

开发（从源代码构建）

git clone https://github.com/G0Osey99/awesome-mineflayer-mcp.git
cd awesome-mineflayer-mcp
npm install
npm run build       # tsc -> dist/
npm run typecheck   # tsc --noEmit
npm test            # vitest (unit tests for the pure logic)
npm run dev         # tsx src/index.ts (run from source, no build step)

架构和完整的设计原理说明见：docs/superpowers/specs/2026-06-28-mineflayer-mcp-server-design.md。

src/
  index.ts        entry (stdio transport, graceful shutdown, crash guards)
  server.ts       builds the McpServer, registers tool groups + resources + prompts
  config.ts       env + constants + safety policy (groups, read-only, command/host allow-lists)
  bot/            manager (lifecycle FSM), plugins, events, wire-events, state, windows, action-locks
  tools/          one module per tool group (+ registry.ts)
  prompts/        guided multi-tool workflows
  resources/      MCP resources + push notifications
  util/           errors, format, result, resolve (name→id + fuzzy), serialize, async, redact
  schemas/        shared Zod fragments

如何添加工具/工具组以及运行本地测试服务器，请参阅 CONTRIBUTING.md。

发布（维护者）

推送 v* 标签即可发布到 npm、GitHub Container Registry（Docker）、MCP Registry，并更新 Smithery——这一切均通过 .github/workflows/ci.yml 完成。npm version 会确保 package.json、src/config.ts 和 server.json 保持同步。

npm version minor        # bumps + syncs versions, commits, and tags
git push --follow-tags   # triggers the release jobs

一次性完整设置说明和分步发布检查清单见 RELEASE.md。发布的 npm 包仅包含 dist/、README.md、LICENSE 和 NOTICE（参见 files 字段）。

故障排除

连接失败现在会返回具体的错误代码和建议（而不是含糊的 INTERNAL）。常见情况：

症状 / 错误	可能原因	解决方法
CONNECT_REFUSED (ECONNREFUSED)	主机/端口错误，或服务未运行	检查 host/port；确认服务已完成启动（默认端口为 25565）。
CONNECT_REFUSED (ENOTFOUND)	无法解析主机名	仔细检查服务地址。
ONLINE_MODE /“unverified username”	服务处于 online-mode；Bot 使用了离线身份验证	使用 auth: "microsoft"，或在服务上设置 online-mode=false。
VERSION_MISMATCH /“outdated client/server”	自动检测到的版本不正确	显式传入 version（例如 "1.20.4"）。
聊天遭拒 /“secure profile”	服务要求对聊天内容签名	使用 disableChatSigning: true 连接。
AUTH_FAILED	Microsoft 令牌已过期或无效	重新运行 npx awesome-mineflayer-mcp setup，或清除 profilesFolder 缓存并重新登录。
run_command 上出现 FORBIDDEN	命令被策略拦截	请参阅安全性 — 调整 MCP_COMMAND_DENY / MCP_COMMAND_ALLOW。
connect_bot 上出现 FORBIDDEN	主机不在允许列表中	将其添加到 MCP_ALLOWED_HOSTS（或取消设置以允许任意主机）。
NO_PATH	Pathfinder 无法到达目标	靠近目标、清除障碍，或放宽 configure_movements 的限制。
Microsoft 设备代码提示	首次使用 MSA 登录	访问 msa_code 事件中的 URL；设置 profilesFolder 以缓存登录信息。

Microsoft 身份验证的首次登录需要交互一次 — 运行 npx awesome-mineflayer-mcp setup 完成登录并缓存令牌。

Docker

此项目包含一个用于无头/自主部署的 Dockerfile（通过 MCP_DEFAULT_* 配置默认账户）：

docker build -t awesome-mineflayer-mcp .

在 /root/.awesome-mineflayer-mcp 挂载一个卷，以持久保存配置和 Microsoft 令牌缓存。（该服务通过 stdio 使用 MCP 通信，因此容器最适合用于自主运行默认账户，而不是供客户端启动。）

限制

• 每个服务进程只能运行一个 Bot（按设计仅支持单会话）。
• 评估需要预置世界。 Minecraft 实时世界不具备确定性，因此 eval/ 中的评估集针对有文档说明的预置种子环境（请参阅 eval/fixture.md）；无法在任意实时服务上进行验证。
• cancel_fish 只能尽力而为（Mineflayer 未提供一流的钓鱼中止功能）。
• Microsoft 身份验证首次运行时需要交互式设备代码（通过 msa_code 事件显示）；使用 profilesFolder 缓存登录信息。

许可证

MIT