VitaminMCP

What VitaminMCP MCP server does

VitaminMCP MCP server lets an AI agent test Minecraft plugins on a live Paper or Purpur server. The plugin under test remains unchanged: the agent interacts with the server through its normal lifecycle, while test players connect as real protocol clients. This makes the server suitable for plugins that are already installed, including plugins the test author did not write.

An agent can control players, execute commands as the console or a player, interact with blocks and entities, use inventories and plugin GUIs, send chat, and move through the world. It can also inspect the server implementation, version, TPS, online players, installed plugins, permissions, live plugin configuration, logs, captured Bukkit events, and recent exceptions.

How it works

Install the VitaminMCP plugin in the Minecraft server, then connect an MCP client through the VitaminMCP runner. The plugin opens an MCP endpoint from inside the running server. The runner is configured on the machine running the AI client, rather than installed into the Minecraft server.

Sessions connect to running servers and can remain separate for proxied networks. Bots may use offline authentication or Microsoft authentication. Actions can be issued one at a time through individual tools or grouped into a bot_run_scenario script. Scenario steps cover spawning, movement, looking, jumping, sneaking, sprinting, block and item interaction, entity interaction, menu clicks, chat, commands, waits, and assertions.

Conditions can be awaited instead of handled with fixed sleeps. Available waits include ticks, block changes, events, player presence, player state, nearby players, open inventories, inventory contents, and matching log entries. Scenario failures identify the failing step and report what the server was doing at that point.

Setup and configuration

Download VitaminMCP.jar from a release or Modrinth, place it in the server's plugins/ directory, and start the Paper or Purpur server. Add the stdio runner to an MCP client with the command npx -y vitaminmcp. Claude Code can add it with claude mcp add vitaminmcp -- npx -y vitaminmcp; clients using JSON MCP configuration can define a server named vitaminmcp with npx and -y vitaminmcp as its command and arguments.

The project is also listed in the official MCP registry as io.github.Backas03/vitaminmcp. After installation, the agent can run the setup prompt to find the running server, check the plugin, and connect. The documentation also covers shared loopback processes, bot setup, configuration defaults, remote servers, SSH, and TLS.

Supported and live-tested Minecraft versions include 1.21 through 1.21.11 and 26.1 through 26.1.2. Minecraft 26.1 requires Java 25. Versions 1.18 through 1.20.6 are planned, and 26.2 or later require a compatibility run before being added.

Tools and capabilities

VitaminMCP MCP server exposes tools for:

• Starting and resetting sessions across one or more servers.
• Reading server information, logs, Bukkit event summaries and records, and recent exceptions.
• Querying players, blocks, inventories, plugins, permissions, commands, and live configuration.
• Running commands as the console or a player.
• Spawning bots, inspecting client-visible chat, titles, boss bars, scoreboards, health, effects, and menus.
• Running complete scenarios and asserting blocks, player state, events, inventories, messages, and reachability.
• Opening a localhost live view of a bot's world or currently open menu.

Limitations and notes

The server is intended for a running Paper or Purpur environment; it is not a mock server or a test framework that instruments plugin source. The inventory state of a plugin GUI is available through the inventory query, while client-facing output is available through bot inspection. Operating-system runner assets are published for Windows x64, Linux x64 and arm64, and macOS Intel and Apple Silicon. The project is licensed under MIT; bundled third-party code has separate license listings.