Minecraft Native MCP

English · 架构与扩展 · 直播集成

让 MCP 客户端控制真正的 Minecraft Java 玩家客户端。提供原生第一视角、血条、饱食度与物品栏，结合结构化空间观察和有边界的连续动作，面向自主生存、AI 实验和游戏直播。

DSH 插件安装（推荐入口）

dsh plugin --profile desktop add https://github.com/tianyingAquila/minecraft-native-mcp/releases/latest/download/minecraft-native-mcp.tgz

重新打开对应 DSH 界面后，顶部会出现 Minecraft 控制台 按钮。准备好依赖时点一次即可在默认浏览器打开控制台；首次使用先在插件面板点“准备依赖”，完成后再打开。也支持 web profile，以及本地开发安装 dsh plugin --profile desktop add link:<本仓库绝对路径>。

首次准备仍需要 Git、Python、Node.js、JDK21、联网以及游戏使用资格。安装包内的插件JS无需编译，但游戏依赖需要下载、Java辅助模组需要构建；不能把首次下载称为零准备。工作副本与存档保存在 $DSH_HOME/minecraft-native-mcp，不写进插件安装目录，更新/卸载插件不会自动删除存档。当前工作副本不会自动覆盖升级，需要停止后备份并重新准备新副本。

插件只管理它自己启动的控制台，卸载/禁用时停止其拥有的进程；不会关掉独立启动的现有控制台。卸载使用 dsh plugin --profile desktop remove minecraft-native-mcp，再重新打开DSH；需要清理工作副本时请先备份世界并手动移走该目录。没有开机启动或系统服务。

已有完整项目时，可在DSH配置中给本插件设置 config.projectDirectory 为项目绝对路径，继续使用原存档和依赖；未设置时使用上面的独立工作目录。

实验性项目，当前针对 Windows + Minecraft Java 1.21.4 + Java 21 验证。 不承诺无人值守通关，也没有完成末影龙全流程验收。

Related MCP server: minecraft-codex-companion

特点

• 原生客户端：Fabric 插件控制真实生存角色，Baritone 辅助寻路，保留正常距离、遮挡、工具耐久和战斗冷却。

• 空间感知：每轮可读水平16格、上下12格的八方向摘要；区分射线可见表面和候选地面连通。复杂地形可读五层 ASCII 切片，原始体素不会全部塞给模型。

• 连续动作：开水平矿道或向下阶梯时，一次决定1–12格、最多90秒；遇流体、近敌、受伤、断崖、落沙或卡住提前交回决策。

• 实际反馈：确认方块变化、角色位移、目标死亡与动作期间最低生命值；目标消失不等于击杀。

• 诊断截图：只取游戏 framebuffer，最长边1280，成功截图间隔30秒，不设小时限额；不截桌面。

• DSH 适配：提供标准 stdio MCP 配置。可选 DeepSeek 自主控制台还能复用 DSH 的私有凭据位置；它不是 DSH 内部代理引擎的替代品。

• DSH 插件入口：通过 bundle 挂载界面按钮、首次准备和进程生命周期管理；独立MCP入口同时保留。

• 可选直播层：游戏内鲸鱼、动态“事件反应＋行动打算”气泡、余额提示及定时暂停；支持抖音直播伴侣捕获，也可供其他平台研究适配。

准备

需要 Windows、Git、Node.js 22+、Python 3.10+、JDK 21，以及合法的 Minecraft 使用资格。安装脚本从官方渠道下载游戏及依赖；游戏文件和账户凭据不随源码发布。下载量较大，首次准备需要联网。

git clone https://github.com/tianyingAquila/minecraft-native-mcp.git
cd minecraft-native-mcp
# JAVA_HOME 指向 JDK 21；java、node、python、git 需要可用。
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/setup_native.ps1

脚本生成项目内独立的客户端、服务端、认证令牌和启动参数。默认使用本机离线测试服与固定角色 DeepSeekFish，不提供微软账户登录流程。不会安装系统服务或开机启动项。

作为独立 MCP 使用

将下面配置放进 DSH 或其他兼容客户端的 MCP 服务器设置，替换成实际绝对路径。具体配置文件位置取决于客户端版本。

{
  "mcpServers": {
    "minecraft-native": {
      "command": "node",
      "args": ["C:/projects/minecraft-native-mcp/src/mcp-server.mjs", "--launch"]
    }
  }
}

--launch 启动本项目独立游戏并解冻，随后等待 MCP 客户端下指令，不会启动 DeepSeek 自主循环或产生模型费用。退出此 MCP 进程会保存停止它启动的游戏。独立模式不需要 DeepSeek API key。

已有原生客户端时，可省略 --launch，通过 FISH_BRIDGE_CONFIG 指向其本机认证配置 JSON（包含 host、port、requireAuth、token）。该模式只接管工具连接，退出时释放动作，不关闭外部游戏。角色名需为 DeepSeekFish；必须安装本仓库客户端辅助插件及固定版本依赖。不要同时让控制台自主循环和外部 MCP 客户端控制同一角色。

示例指令：

先读取游戏状态和空间概览，找一个合适方向开4格矿道。遇到危险先停止，依据实际结果决定下一步。

可选：DeepSeek 自主控制台

$env:DEEPSEEK_API_KEY = "YOUR_PRIVATE_KEY"
npm start

打开 http://127.0.0.1:21940，选择世界、设置时长，准备后开始。也支持从 DSH_HOME（默认用户目录 .dsh）的 .credentials.yaml 读取 refs.DEEPSEEK_API_KEY。不要把真实密钥保存到仓库。只使用官方 DeepSeek API 和人民币余额检查，低于¥1或查询失败时停止新请求。

控制台默认每场120分钟。暂停会保存冻结游戏；停止会退出项目游戏进程。测试规则默认包含生命回复I、抗性提升I、夜视I及死亡不掉落，模型知道这些规则。需要普通规则可研究 src/minecraft.mjs 的数据包生成；当前没有一键规则切换界面。

工具概览

确切参数以 MCP tools/list 为准。独立 MCP 的截图直接作为 image 内容返回，客户端及所用模型需要支持图像工具结果。标准工具不包含任意系统命令或一键通关脚本。

验证与边界

npm test

测试需要先准备固定版本的上游 agent runtime。原生动作、连续矿道、空间几何、冻结及挂件有本地受控验证；独立 MCP 的初始化、列工具及只读真实游戏调用另行烟测。全新电脑安装、其他系统、其他游戏版本、第三方 MCP 客户端 UI、长局稳定性及完整通关仍需验证。空间连通是保守完整方块估计，半砖/楼梯、跳跃、游泳、攀爬与未加载区域不能当作已验证路径。

致谢与许可

本项目核心基于 mcpfabric 和 Baritone，不是从零实现的完整 Minecraft 控制栈。鲸鱼素材来自 DeepSeek Balance Whale Widget。项目介绍结构参考了 minecraft-mcp-server，本项目使用原生 Fabric 客户端路线。

新增代码采用 MIT，依赖和素材保留各自许可证，见 THIRD_PARTY.md。欢迎提交问题、平台适配和可复现的改进。