VitaminMCP

面向 AI 智能体的 Minecraft 自动化测试 MCP 服务器插件。

VitaminMCP 是一个 Paper/Purpur 服务器插件。 将 VitaminMCP.jar 放入 plugins/，启动服务器，它就会在运行中的服务器内部打开一个 MCP 端点——这样 AI 智能体就能驱动该服务器并读回发生的事件，而真实的机器人客户端则通过 Minecraft 协议连接到它。

你正在测试的插件本身完全不需要任何改动。 无需采用测试框架，无需对源码进行插桩，无需编译针对的测试装置，也没有模拟服务器来顶替真实服务器：被测插件在真实服务器上经历其完整的生命周期运行，而 VitaminMCP 就在隔壁的插件槽位观察它。这也意味着它适用于并非你编写的插件——任何已安装的插件都可以测试。

通过 MCP 工具驱动真实的 Minecraft 服务器和真实玩家，无需打开游戏即可运行端到端插件测试。

• 生成并控制测试玩家——真实的协议客户端，而非模拟的 Player 对象

• 以控制台或玩家身份执行命令

• 打开、读取、点击背包和插件 GUI 并对其断言

• 右键点击 NPC 和村民，就像真正触发商店或任务发布者那样

• 移动玩家、破坏和使用方块、聊天

• 等待事件和条件，而不是休眠

• 对方块、玩家、事件、背包以及玩家收到的消息进行断言

• 读取玩家的整个屏幕：菜单、聊天、动作栏、标题、Boss 血条、记分板

• 读取实时服务器状态：事件、日志、异常、权限

• 同时驱动多台服务器——BungeeCord 网络的每个后端各一个会话，机器人跨所有服务器保持连接

• Paper / Purpur 1.21 至 1.21.11，一次安装即可——运行器会自动判断服务器使用的协议并适配

完整用法见 docs/usage.md。贡献规则见 CONTRIBUTING.md，发布步骤见 docs/publishing.md。

各部分如何协同

三个 jar，位于三个不同的位置。只有第一个是 Minecraft 插件。

  your MCP client (Claude Code, Cursor, Codex, Gemini CLI, ...)
        |
        |  stdio
        v
  mcp-server.jar ---- HTTP(S) + token ---->  VitaminMCP.jar  <- the plugin, inside your server
        |                                    sees events, logs, exceptions, live state
        |  spawns
        v
  Node runner -------- Minecraft protocol ->  the same server, on :25565
                                             sees what a player's client was actually sent

插件能看到服务器端的事件、日志、权限和状态；Node 运行器能看到真实客户端收到的内容。默认是只读模式，机器人是可选的。

Related MCP server: Minecraft RCON MCP Server

示例

让智能体测试一个插件，或者向 bot_run_scenario 传入一个场景：

[
  {"action":"spawn", "bot":"Tester1"},
  {"action":"command", "bot":"Tester1", "command":"shop"},
  {"action":"wait_for", "condition":"inventory_open", "name":"Tester1", "title":"Shop"},
  {"action":"assert_inventory", "bot":"Tester1", "slots":[
    {"slot":11, "material":"DIAMOND_SWORD", "name":"Diamond Sword"}
  ]}
]

工具

分为两组。会话工具位于 mcp-server 中，始终存在。智能体工具由插件代理，因此存在哪些工具取决于你连接的服务器——session_start 会在 agentTools 中返回它们的真实定义。

连接

玩家

服务器

世界与状态

事件与日志

等待

wait_for 会阻塞直到某个条件成立，在服务器内部每 tick 检查一次。

没有 sleep，也不会有。 固定等待是对时机的猜测——在空闲服务器上正确，在繁忙服务器上错误——这正是产生不稳定测试的全部机制。超时时，wait_for 会返回那一刻的事件和日志。

动作——场景步骤

可在 bot_run_scenario 内部使用。

断言——场景步骤

验证是关键，因此这里的功能面最广。

使用 bot_inspect 获取消息、屏幕状态和效果；使用 state_query 获取服务器状态。代理参数直接平铺在顶层传递。完整参数见 docs/usage.md。

要求

以下是使用预构建版本的要求：

版本支持

按操作系统划分的运行器支持

图例： 支持 · 已计划或需要指定运行时 · 🔴 不支持。

目前支持 1.21 至 1.21.11，每个版本都在矩阵中运行（versions.yaml）。1.21.11 是这条线的终点——此后 Minecraft 改用日历版本，所以 1.21.11 之后是 26.1 和 26.2，而不是 1.21.12。这些版本已经发布，但尚未加入矩阵：添加一个版本需要对真实服务器进行一次兼容性运行，并检查运行器自带的数据是否仍然覆盖该版本，而绝不是只编辑 versions.yaml。

**每个平台的支持声明来自哪里。**矩阵在 Windows 上运行，针对它自行下载的 Paper 构建版本——因此它在任何主机上验证的结果都是一样的，因为它所连接的服务器是同一台服务器。每个版本都在该运行器对应的操作系统上构建其原生运行器，绝不交叉构建；每个运行器都会在 CI 中启动，并且在上传前必须以预期的退出码拒绝自己的入口点。世界视图是唯一仍仅限 Windows 的部分，并且在提供该功能的地方已明确说明。

**无论版本如何，你只需安装一个 Node 运行器。**它会询问服务器使用什么协议，并选择匹配的 minecraft-data 条目，因此无需选择特定协议的运动器。

从源码构建

大多数用户不需要本节。贡献者需要 JDK 21 和 Node/npm：

./gradlew build
cd bot/bot-runner-node && npm ci && npm test

原生运行器通过 npm run build:sea -- win32-x64、linux-x64、linux-arm64、darwin-x64 或 darwin-arm64 构建。macOS 资源在发布工作流中会获得 ad-hoc 签名。

在支持范围之外，系统会明确失败而不是行为异常：旧版服务器会拒绝加载智能体，而协议没有 minecraft-data 条目的服务器会在启动时被明确指出。

智能体支持和机器人支持也可能不同。智能体需要兼容的 Paper API；机器人需要匹配的 minecraft-data 条目和支持的运行器环境。因此，在机器人能够加入之前，服务器可能已经被智能体读取——检查、日志和事件在没有机器人的情况下仍然正常运作。

安装

分为两部分，单独使用任何一部分都没有意义：一个 你机器上的 MCP 服务器，由你的客户端启动；以及 Minecraft 服务器上的智能体插件，所有值得询问的事情都发生在那里。

1. 连接你的 MCP 客户端

MCP 服务器是纯 stdio：任何能够启动 npx -y vitaminmcp 的客户端都可以——Claude Code、Cursor、Codex、Gemini CLI、Windsurf、Claude Desktop、VS Code。这是每个客户端在自己文件中表达的同一个配置：

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "npx",
      "args": ["-y", "vitaminmcp"]
    }
  }
}

Claude Code 有一个快捷方式：插件带来 MCP 服务器以及如何驱动它的实用知识，作为一个在问题需要时自动加载的技能。在 Claude Code 提示符中输入以下内容（它们是 Claude Code 命令，不是 shell 命令）：

/plugin marketplace add Backas03/VitaminMCP
/plugin install vitaminmcp@vitaminmcp

在其他任何地方，将该服务器注册到该客户端存放 MCP 配置的位置：

每个工具在每个客户端中的工作方式都相同。只有 Claude Code 能获得插件的技能——即书面的测试手册。其他客户端仍然会在调用时获得重要的操作知识：session_start 返回智能体的完整工具定义，工具描述也自带各自的警告。

以上就是整个客户端部分。无需手动下载任何东西，也不用为路径烦恼：vitaminmcp 包会在首次运行时获取所需的 jar 文件，存入 ~/.vitaminmcp/jars/<version>/，每个文件都会根据发布时固定在包中的 SHA-256 进行校验。

mcp-server.jar 有两兆字节，需要等待下载。如果安装了 Node，会直接使用源码 runner，不会下载任何 runner 资源文件。如果没有 Node，启动器会为当前平台选择原生 runner 资源文件，每个受支持的平台都有对应的资源。

mcp-server 使用 stdio 通信。它没有端口，也没有令牌：它是客户端的一个子进程，因此信任关系已经存在。只有 agent 端会跨越网络，所以也只有 agent 端需要进行身份验证。

需要 Node 18.17+ 来运行 npx，还需要 Java 21 来运行这些 jar。没有 npm，或者没有任何可用的下载工具？改为从 jar 安装。

2. 在服务器上安装插件

只需提出要求，agent 就会完成。MCP 服务器会发布一个 setup 提示词，引导 agent 完成这一步——它会检查服务器是否为 Paper 1.21+，把 jar 放入 plugins/，重启并连接。客户端会以提示词自身的名称展示 MCP 提示词，这些名称根据 服务器 注册时所用的名称构建。在 Claude Code 中：

/mcp__plugin_vitaminmcp_vitaminmcp__setup    # installed as the plugin
/mcp__vitaminmcp__setup                      # added with claude mcp add vitaminmcp

/mcp 会列出你的服务器实际叫什么。如果客户端在别处列出提示词（或者根本不列出），直接用自然语言询问即可：

提示词： 在我位于 ~/servers/test 的 Minecraft 服务器上设置 VitaminMCP，并连接到它。

或者手动操作：

从 Releases 下载 VitaminMCP.jar 到服务器的 plugins/——这是一个普通的 Bukkit/Paper 插件，不需要服务器启动参数，也不需要附加 Java agent——然后启动服务器。

[VitaminMCP] No auth token was configured, so one was generated and written to config.yml: kQ8s...
[VitaminMCP] MCP endpoint listening on http://127.0.0.1:25585/mcp

你不需要复制那个令牌。 同一台机器上的客户端会从 agent 自身的握手中读取它。只有当客户端位于其他机器上时才需要复制。

这就是最简安装。其他所有设置都记录在 config.yml 中，并且解释了每个默认值为何如此。在改动任何内容之前，有三个默认值需要了解：

• read-only: true 是默认值。 像 command_exec 这样改变状态的工具根本不会暴露——即使有有效令牌，默认安装也无法更改服务器。只有在需要时才将其关闭。

• 端点绝不会在未认证的情况下开放。 空的 auth-token 会被填入一个生成的令牌，而不是被放行；如果无法写入该令牌，插件仍会拒绝启动。始终不可妥协的是必须存在一个令牌；让你从崩溃日志里翻出一个从来都不是其中应有之义。

• 将 bind-address 移出回环会使 TLS 成为强制要求。 令牌授予控制台访问权限，而通过普通 HTTP 传输时，它会以明文穿越网络，路径上的任何东西都能读取它。因此，这种组合会导致拒绝启动，而不是发出警告。可以通过 tls.enabled（agent 自己提供 HTTPS）或 tls.terminated-upstream（由前置代理终止它）来满足要求。agent 不会为你生成自签名证书——这虽然方便，但会让每个客户端都学会跳过验证。

3. 服务器设置（如果需要机器人）

如果你只需要 agent，可以跳过本节。

机器人使用离线模式，并在机器人名称被复用时复用相同的确定性 UUID：

# server.properties
online-mode=false

绝不要将离线模式服务器暴露到互联网。 这是测试平台配置，不是生产配置。正常的 Node 登录不需要任何 BungeeCord 设置。

复用机器人名称会复用其确定性的离线 UUID。只有在测试需要传递 clientIp 并需要伪造地址或 UUID 时，才显式设置 BungeeCord 转发。

move_to 默认会走向其目标，使用相同的客户端物理循环在两点之间发送移动数据包。这意味着监听压力板和移动事件的插件会观察到这条路线。找不到路径时，会以 No path exists 失败；在 timeoutMillis 之前未到达时，会以 did not arrive ... within ... 失败。

对于只需要机器人位于某个坐标的设置步骤，请使用 "mode":"teleport"。这会保留旧版的单一位置数据包行为，而且速度仍然很快，但不会触发行走玩家本会引发的事件。

行走不会挖穿或放置方块。寻路器被刻意配置为只进行普通移动，因此测试墙仍然是测试墙。

4. 连接

直接询问即可。这些是提示词——复制一个并填入你自己的值。

本机上的服务器

提示词： 连接到本机上的 Minecraft 服务器，然后告诉我服务器版本以及加载了哪些插件。

通过 SSH 隧道——说明隧道转发了哪些本地端口

提示词： 测试服务器已通过隧道连接到本机——Minecraft 在 localhost:10000，agent 在 localhost:25685。令牌是 kQ8s…。连接并确认它在线。

或者不让令牌出现在对话中，而是指向一个文件——agent 会读取该文件并将其传给 session_start：

提示词： 测试服务器已通过隧道连接到本机——Minecraft 在 localhost:10000，agent 在 localhost:25685。令牌位于 ~/.secrets/vitaminmcp-token。连接并确认它在线。

如果希望令牌完全不出现任何提示词中，可以在 MCP 服务器的环境中设置 VITAMINMCP_TOKEN（位于客户端配置中 "command" 旁边的 "env" 块）——只要没有给出 token 参数，session_start 就会回退到该环境变量。

远程，通过 TLS——粘贴 agent 在启动时打印的配置块

提示词： 使用以下信息连接：host 203.0.113.10，mcpPort 25585，tls true，token YLwNyFij…，fingerprint sha256:ffb61d8f…f163。Minecraft 位于 25565。

或者把令牌放在文件中而不是对话中：

提示词： 使用以下信息连接：host 203.0.113.10，mcpPort 25585，tls true，fingerprint sha256:ffb61d8f…f163，令牌位于 ~/.secrets/vitaminmcp-token。Minecraft 位于 25565。

对于不在本机上的任何情况，请包含端口号和令牌。 缺少这些信息时，agent 只能猜测默认值，而猜错会表现为令牌被拒绝，而不是地址错误——无论缺少哪个细节，失败表现都一样。

agent 调用的内容：session_start

session_start

无需参数。agent 在运行期间会将其主机、两个端口和令牌写入 ~/.vitaminmcp/agents/<port>.properties，session_start 会读取这些信息——因此对于本机上的服务器，无需传递任何内容，也无需查找任何内容。成功连接后，会返回服务器版本、TPS、插件列表、agent 的真实工具定义和当前会话列表。runner 进程已退出的会话会从该列表中移除。

只传递不同的部分。其他机器上的服务器需要 host 和 token，因为在本机生成的令牌对另一台机器上的服务器说明不了任何问题，也不会被发送到那里：

{
  "host": "203.0.113.10",
  "token": "auth-token from config.yml",
  "tls": "true",
  "tlsFingerprint": "sha256:ffb61d8f...f163"
}

代理网络由多台服务器组成。 每个后端打开一个会话——它们可以共存，启动一个绝不会干扰另一个，这一点很重要，因为关闭会话会断开其机器人。port 在每个会话中都是代理的端口；区分它们的是 mcpPort，即每个后端内部的 agent。当本地运行多个 agent 时，这也是在它们之间进行选择的方式；省略它会产生一个列出它们的错误，而不是一次猜测。

session_start {"session": "lobby",    "mcpPort": 25585, "port": 25577}
session_start {"session": "survival", "mcpPort": 25586, "port": 25577}
bot_spawn     {"session": "lobby", "name": "Tester1"}

所有其他工具都接受 session 参数。省略它时，只有在恰好打开一个会话的情况下才能解析；有多个会话时，会产生一个列出它们的错误，而不是猜测你指的是哪台服务器。完整教程见 docs/usage.md。

改为从 jar 安装

npx 是一种便利方式，并非必需。每个 release 都附带两个构件，外加可选的平台 runner 资源，并且每个构件都放在不同的位置：

如果想自己构建它们：

./gradlew dist

无论哪种方式，都要让客户端指向 jar 而不是包——注册方式与步骤 1 相同，但命令不同：

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "java",
      "args": ["-jar", "/absolute/path/mcp-server.jar"]
    }
  }
}

或者在 Claude Code 中：claude mcp add vitaminmcp -- java -jar /absolute/path/mcp-server.jar。

VITAMINMCP_RUNNER_JAR 或 session_start 的 runnerJar 参数用于指定 Node 脚本或原生 runner。

一个 Node runner，覆盖所有受支持的版本。 它会在任何机器人连接之前 ping 服务器，并选择匹配的 mineflayer 数据，因此同一个源码 runner 可用于 1.21 到 1.21.11。

另一台机器上的服务器

有两种方式：通过 SSH 转发端口，或者使用 TLS 暴露 agent。如果你已经有到那台机器的 SSH，隧道方式工作量更少，也不会暴露任何内容。

通过 SSH 隧道

让 agent 保持其回环默认值，并转发两个端口：

ssh -L 25585:127.0.0.1:25585 -L 25565:127.0.0.1:25565 user@your-server

然后像所有内容都是本机一样连接——host: "127.0.0.1"，不启用 tls，不启用 tlsFingerprint。agent 看到的是一个回环连接，因为从它这一侧来看，事实就是如此。服务器上的任何内容都不会发布到网络，令牌也绝不会以明文形式穿越网络：SSH 就是本来需要 TLS 提供的传输安全。

请转发两个端口。mcpPort 是工具访问 agent 的方式，port 是机器人连接的位置——只转发第一个端口，你会得到一个可用的 server_info 和一个无法连接的 bot_spawn。

选择真正空闲的本地端口。 ssh -L 会绑定本地一侧，如果你机器上已经有程序占用了该端口，隧道不会接管它——你的请求反而会到达另一个程序。由此产生的失败具有误导性：在 25585 上响应的另一个 VitaminMCP agent 会拒绝你的令牌，因此它看起来像是令牌错误，而不是目标错误。如有疑问，请映射到一个不同的本地端口（-L 25685:127.0.0.1:25585）并将该端口作为 mcpPort 传入。

使用 TLS 暴露 agent

一旦 bind-address 离开回环，agent 在没有 TLS 的情况下就不会启动。设置好证书并启动它，agent 会打印连接所需的一切信息：

[VitaminMCP] MCP endpoint listening on https://203.0.113.10:25585/mcp
[VitaminMCP] Connect with session_start:
  "host": "203.0.113.10", "mcpPort": 25585, "tls": "true",
  "token": "YLwNyFij...",
  "tlsFingerprint": "sha256:ffb61d8f...f163"

粘贴即可完成。即使使用自签名证书，客户端也无需安装任何东西——tlsFingerprint 会固定那一张证书。无需导出、无需复制、无需信任库。

使用真实证书（Let's Encrypt 等）时，去掉 tlsFingerprint，验证就会正常进行。

针对多个版本运行

同一个场景可以一次跑遍所有受支持的版本。矩阵是 versions.yaml，而不是代码——添加一个版本就是一个块。服务器 jar 会从 PaperMC API 下载并以原生方式启动（不需要 Docker、不需要 ViaProxy，也没有额外的转换层）。

协议刻意不放在该文件中。 Node runner 会询问每台服务器使用什么协议，并选择匹配的 minecraft-data 条目，因此一个版本除了要下载的构建之外，无需在该文件中添加任何内容。

1.21.11 之后的版本——由于 1.21 系列止步于此，现在指 26.1 及以上——在加入之前需要进行一次兼容性运行，并检查 runner 精简后的数据仍然覆盖它们。runner 会根据服务器握手选择匹配的数据版本；当没有对应条目时，它会明确拒绝，而不是勉强运行。

许可证

MIT——参见 LICENSE。

分发的 jar 包捆绑了第三方代码，并对其进行了重定位，以免与服务器或其他插件发生冲突：

它们的许可证和声明文件随 jar 包一同分发，位于 META-INF/ 下——重定位一个包只是给它改名，并不会免除携带声明文件的义务。

paper-api、log4j-core 和 JetBrains annotations 仅用于编译，不会随包分发。该智能体针对 Paper 的 API 进行编译，该 API 采用 LGPL-3.0 许可；jar 包中不包含它，服务器本身已提供该 API。这里没有任何内容涉及 paper-server（GPL-3.0）——该智能体仅使用 Bukkit/Paper API，绝不使用 NMS。