VitaminMCP
MCP server that lets AI agents test Minecraft Paper plugins on a live server with bot
The repository was last updated 29 days ago and is published under MIT.
- Pricing
- Open source
- Platforms
- API, CLI, Linux
- Runs
- Locally
- GitHub stars
- 2
- Last commit
- 29 days ago
- Language
- Java
Similar MCP servers
About VitaminMCP
VitaminMCP is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
The README says VitaminMCP is a Paper/Purpur plugin that opens an MCP endpoint from inside a running server. An AI client such as Claude Code, Cursor or Codex connects through a local npm stdio package, then drives the server, spawns protocol-level bot players and reads back logs, events, inventories and chat.
The main difference from typical plugin test frameworks is that the plugin under test is not modified or wrapped. It runs on a real server through its normal lifecycle, so testing covers plugins the author did not write. Bots connect over the actual Minecraft protocol rather than acting as mock player objects.
The project suits Minecraft plugin developers and server operators who want an agent to run scripted or exploratory checks on commands, GUIs, NPCs and permissions. Support is listed per Minecraft version, with 1.21 through 1.21.11 and 26.1 through 26.1.2 marked as live-tested.
Install
Run in a terminal
claude mcp add vitaminmcp -- npx -y vitaminmcpAdd to claude_desktop_config.json
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": [
"-y",
"vitaminmcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": [
"-y",
"vitaminmcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"vitaminmcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"vitaminmcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": [
"-y",
"vitaminmcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": [
"-y",
"vitaminmcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (14)
Taken from the project documentation; the running server may differ.
- 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 for players, blocks, inventories and plugins
- command_exec
- Run a command as the console or as any player
- wait_for
- Block until a condition holds
- 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
- bot_view
- Live localhost viewer for one bot
What it does
- Live server control
- Runs commands as console or as a player and reads server state such as players, blocks, inventories and plugin configuration.
- Protocol bot players
- Spawns offline or Microsoft-authenticated bots that join over the real Minecraft protocol and can move, click and chat.
- Scripted test scenarios
- Runs multi-step scenarios with block, player, event and inventory assertions, reporting the failing step and server state.
- Log and event inspection
- Queries server logs, captured Bukkit events and distinct exceptions with stack traces on demand.
- Multi-server sessions
- Opens one session per backend server, for example each backend of a BungeeCord network.
- Live bot viewer
- Provides a localhost viewer showing a bot's world or the menu it has open.
Good for
- Check that a shop or quest NPC responds correctly when a bot right-clicks it
- Verify plugin GUI slots and clicks after a code change
- Test permission-gated commands as console and as different players
- Investigate exceptions and event sequences from a running server during development
- Run regression scenarios across several Minecraft versions
Pricing
Open source
MIT licensed and free to use.
VitaminMCP FAQ
Do I need to change the plugin I want to test?
The README says no. The plugin under test runs unchanged on a real server, with no test framework to adopt and no source to instrument.
Which MCP clients does it work with?
The README names Claude Code, Cursor, Codex, Gemini CLI and Claude Desktop, and says any MCP client can connect.
Which Minecraft versions are supported?
The README lists 1.21 through 1.21.11 and 26.1 through 26.1.2 as supported and live-tested. Later releases need a compatibility run before they are added.
How is it installed?
Install the VitaminMCP.jar plugin on the server, then add the npm package vitaminmcp to your AI client with npx.
Is VitaminMCP free?
Yes. VitaminMCP is open source, so you can use and self-host it for free.
How do I add VitaminMCP to Claude Code?
Run this command in your terminal: claude mcp add vitaminmcp -- npx -y vitaminmcp
What are the best alternatives to VitaminMCP?
The closest alternatives to VitaminMCP are MCP Server, Api Test MCP, MCP Server Commands, HeadlessMc and Mobai MCP.
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.
