VitaminMCP
An MCP server that enables AI agents to perform real end-to-end testing of Minecraft server plugins using bots and server introspection.
Install / Use
claude mcp add Backas03 -- npx -y github:Backas03/VitaminMCPIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of VitaminMCP
VitaminMCP scores 79/100 on our quality scale, 2457th of 2,758 Automation skills we index.
Its MCP Server is 8.6 KB long, well organised into 9 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated yesterday, so VitaminMCP is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-22. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
VitaminMCP compared with similar skills
All 4 of these similar skills score higher than VitaminMCP; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| VitaminMCP (this skill)by Backas03 | 79 | 3 | 1d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.5k | today | CLAUDE.md |
Frequently asked questions
- How do I install VitaminMCP?
- Run
claude mcp add Backas03 -- npx -y github:Backas03/VitaminMCP. The install tabs above show the steps for each supported agent. - Which AI agents does VitaminMCP work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is VitaminMCP safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is VitaminMCP still maintained?
- The repository was last updated yesterday, so VitaminMCP is actively maintained.
Skill content
View source on GitHubVitaminMCP
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
Playerobjects - 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
| Tool | What it does |
|---|---|
| session_start | Connect to a running server; several sessions at once for proxied networks |
| session_reset | Disconnect every bot, or close a session |
| server_info | Implementation, version, TPS, online players, installed plugins |
| logs_query | Search server logs by severity and regular expression |
| events_summary | Count captured Bukkit events by type over a time window |
| events_query | Read individual captured events, filtered by type and player |
| exceptions_recent | Distinct exceptions with counts; full stack trace on demand |
| state_query | Live server state — player (including permission checks), block, inventory (the only place a plugin GUI's contents exist), plugin (commands, permissions, live config) |
| command_exec | Run a command as the console or as any player, permissions and all |
| wait_for | Block until a condition holds — ticks, block_is, block_is_not, event, player_online, player_offline, player_near, player_state, inventory_open, inventory_contains, log_matches |
| bot_spawn | Connect an offline or Microsoft-authenticated Minecraft protocol client as a test player |
| bot_inspect | Everything the bot's client was sent: chat, action bar, titles, boss bars, scoreboard, health, effects, open menu |
| bot_run_scenario | Run a whole scripted test in one call; a failure reports the failing step and what the server was doing at that moment |
| bot_view | Live localhost viewer for one bot — the world, or the menu it has open |
Scenario steps
bot_run_scenario scripts a whole test from these steps — a failure reports the failing step and
what the server was doing at that moment:
| Category | Step | What it does |
|---|---|---|
| World & movement | spawn | Connect the bot and wait until it is standing in the world |
| | despawn | Disconnect the bot |
| | move_to | Walk there through real physics — pressure plates and move listeners fire; teleport mode for setup |
| | look_at | Face a block or position |
| | jump | Jump |
| | sneak | Start or stop sneaking |
| | sprint | Start or stop sprinting |
| Blocks & items | break_block | Break a block, through real digging |
| | place_block | Place a block from the hand |
| | use_block | Right-click a block — buttons, doors, chests |
| | hold_item | Put an item into the main hand |
| | drop_item | Drop the held item |
| Interaction | use_entity | Right-click an entity — the way a shop or quest NPC is actually triggered |
| | attack_entity | Attack an entity |
| | click_slot | Click a slot in the open menu or GUI |
| | close_menu | Close the open menu |
| | chat | Send a chat message as the bot |
| | command | Send a command as the bot, permissions and all |
| | console | Run a console command mid-scenario |
| Waiting | wait_for | Block until a condition holds — every wait_for condition is available as a step |
| Assertions | assert_block | Assert what a block is |
| | assert_player | Assert a player's live state — position, game mode, op, health |
| | assert_event | Assert that an event fired on the server |
| | assert_inventory | Assert the slots of the open GUI or an inventory |
| | assert_message | Assert what the bot's client was told — chat, action bar, title |
| | assert_reachable | Assert a position can actually be walked to |
How the three pieces fit together, what every tool and step accepts, and an example scenario are in docs/reference.md.
Version support
| Minecraft version | Windows | Linux | macOS | Status |
|---|:---:|:---:|:---:|---|
| 1.18 – 1.20.6 | 🟡 | 🟡 | 🟡 | Planned; below the current agent floor (1.21) |
| 1.21 – 1.21.11 | 🟢 | 🟢 | 🟢 | Supported and live-tested |
| 26.1 – 26.1.2 | 🟢 | 🟢 | 🟢 | Supported and live-tested |
| 26.2 – 26.3, agent | 🟢 | 🟢 | 🟢 | Agent supported: logs, events, state and commands, checked by hand on Paper 26.2-134 and 26.3-200 |
| 26.2 – 26.3, bots | 🔴 | 🔴 | 🔴 | Not yet: mineflayer stops at 26.1 (#4). session_start opens for the agent and says why bots cannot join |
| Later releases | 🟡 | 🟡 | 🟡 | Each needs a compatibility run before it is added |
Runner support by operating system
| Operating system | Node source runner | Native runner asset | Meaning | |---|:---:|:---:|---| | Windows x64 | 🟢 | 🟢 | Published, and the platform the matrix is run on | | Linux x64 / arm64 | 🟢 | 🟢 | Published since 3.0.0 | | macOS Intel / Apple Silicon | 🟢 | 🟢 | Published since 3.0.0, ad-hoc signed |
Legend: 🟢 supported · 🟡 planned or requires the stated runtime · 🔴 unsupported.
Requirements, where each claim comes from, and how the version matrix is run are in docs/reference.md.
Setup
1. Install the plugin — download VitaminMCP.jar from the
latest release (or from
Modrinth), drop it into plugins/, and start the server.
2. Add the MCP server to your AI client — it runs on your machine, not on the server:
Claude Code
claude mcp add vitaminmcp -- npx -y vitaminmcp
Claude Desktop, Cursor, or any client with a JSON MCP config:
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": ["-y", "vitaminmcp"]
}
}
}
It is also on the official MCP registry as
io.github.Backas03/vitaminmcp, so clients with a registry catalogue can add it from there.
Clients that keep one stdio process per loaded project can instead connect all projects to
one shared loopback server. On Windows,
npx -y vitaminmcp service install installs and verifies that shared server in one command.
3. Let the agent wire itself up — ask it to run the setup prompt (in Claude Code:
/mcp__vitaminmcp__setup). It finds the running server, checks the plugin, and connects.
That is enough for a server on this machine. The Claude Code plugin (which also brings the testing
skill), other clients, installing from the jars, config.yml defaults, bot setup, and reaching a
server behind SSH or TLS are all in INSTALL.md.
Full installation and usage docs: backas03.github.io/VitaminMCP — every tool, scenario runs, multi-server sessions, and remote-server setup are covered in docs/usage.md.
Contributing and building
Contribution rules are in CONTRIBUTING.md, building from source in docs/reference.md, and release steps in docs/publishing.md.
License
MIT — see LICENSE. The third-party code bundled in the jars, and its licenses, are listed in docs/reference.md.
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.5kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
