VitaminMCP MCP server

VitaminMCP

Test your plugins with an AI agent — on a real running server, with real players.

Documentation · Modrinth · npm · Issues

VitaminMCP is a Paper/Purpur plugin that opens an MCP (Model Context Protocol) endpoint from inside your running server. Connect an AI agent — Claude Code, Cursor, Codex, Gemini CLI, any MCP client — and it can drive the server and read back what happened, while real bot clients join over the actual Minecraft protocol.

Nothing about the plugin you are testing changes. No test framework to adopt, no source to instrument, no mock server: the plugin under test runs on a real server through its real lifecycle. That also means it works on plugins you did not write — anything installed is testable.

What the agent can do

• 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
• 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

MCP tools

Scenario steps

botrunscenario scripts a whole test from these steps — a failure reports the failing step and what the server was doing at that moment:

Shortened. The full README is on GitHub.