VitaminMCP

Minecraft automation testing MCP server plugin for AI agents.

VitaminMCP is a Paper/Purpur server plugin. Drop VitaminMCP.jar into plugins/, start the server, and it opens an MCP endpoint from inside the running server — so an AI agent can drive that server and read back what happened, while real bot clients connect to it over the Minecraft protocol.

Nothing about the plugin you are testing changes. No test framework to adopt, no source to instrument, no harness to compile against, no mock server standing in for a real one: the plugin under test runs on a real server through its real lifecycle, and VitaminMCP watches it from the next plugin slot over. Which also means it works on plugins you did not write — anything already installed is testable.

Drive a real Minecraft server and real players through MCP tools, and run end-to-end plugin tests without opening the game.

• Spawn and control test players — real protocol clients, not mock Player objects
• Execute commands as the console or as a player
• Open, read, click and assert on inventories and plugin GUIs
• Right-click NPCs and villagers, the way a shop or quest giver is actually triggered
• Move players, break and use blocks, chat
• Wait for events and conditions instead of sleeping
• Assert on blocks, players, events, inventories and the messages a player received
• Read the player's whole screen: menus, chat, action bar, titles, boss bars, scoreboard
• Read live server state: events, logs, exceptions, permissions
• Drive several servers at once — one session per backend of a BungeeCord network, bots staying connected across all of them
• Paper / Purpur 1.21 through 1.21.11, from one install — the runner works out which protocol the server speaks and adapts

Full usage is in docs/usage.md. Contribution rules are in CONTRIBUTING.md, and release steps are in docs/publishing.md.

How it fits together

Three jars, in three different places. Only the first is a Minecraft plugin.

  your MCP client (Claude Code, ...)
        |
        |  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

The plugin sees server-side events, logs, permissions and state; the Node runner sees what a real client receives. Read-only mode is the default, and bots are optional.

Example

Ask the agent to test a plugin, or pass a scenario to 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"}
  ]}
]

Tools

Two groups. Session tools live in mcp-server and are always present. Agent tools are proxied from the plugin, so which ones exist is decided by the server you connected to — session_start returns their real definitions in agentTools.

Connection

... View full README on GitHub