{
  "markdown": "# VitaminMCP\n\n**Test your plugins with an AI agent — on a real running server, with real players.**\n\n![VitaminMCP demo — an AI agent driving a real Minecraft server](docs/demo.gif)\n\n[Documentation](https://backas03.github.io/VitaminMCP/) · [Modrinth](https://modrinth.com/plugin/vitaminmcp) · [npm](https://www.npmjs.com/package/vitaminmcp) · [Issues](https://github.com/Backas03/VitaminMCP/issues)\n\nVitaminMCP is a Paper/Purpur plugin that opens an [MCP (Model Context Protocol)](https://modelcontextprotocol.io)\nendpoint from inside your running server. Connect an AI agent — Claude Code, Cursor, Codex, Gemini\nCLI, any MCP client — and it can drive the server and read back what happened, while real bot\nclients join over the actual Minecraft protocol.\n\n**Nothing about the plugin you are testing changes.** No test framework to adopt, no source to\ninstrument, no mock server: the plugin under test runs on a real server through its real\nlifecycle. That also means it works on plugins you did not write — anything installed is testable.\n\n## What the agent can do\n\n- Spawn and control test players — real protocol clients, not mock `Player` objects\n- Execute commands as the console or as a player\n- Open, read, click and assert on inventories and plugin GUIs\n- Right-click NPCs and villagers, the way a shop or quest giver is actually triggered\n- Move players, break and use blocks, chat\n- Wait for events and conditions instead of sleeping\n- Read the player's whole screen: menus, chat, action bar, titles, boss bars, scoreboard\n- Read live server state: events, logs, exceptions, permissions\n- Drive several servers at once — one session per backend of a BungeeCord network\n\n## MCP tools\n\n| Tool | What it does |\n|---|---|\n| `session_start` | Connect to a running server; several sessions at once for proxied networks |\n| `session_reset` | Disconnect every bot, or close a session |\n| `server_info` | Implementation, version, TPS, online players, installed plugins |\n| `logs_query` | Search server logs by severity and regular expression |\n| `events_summary` | Count captured Bukkit events by type over a time window |\n| `events_query` | Read individual captured events, filtered by type and player |\n| `exceptions_recent` | Distinct exceptions with counts; full stack trace on demand |\n| `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) |\n| `command_exec` | Run a command as the console or as any player, permissions and all |\n| `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` |\n| `bot_spawn` | Connect a real Minecraft protocol client as a test player |\n| `bot_inspect` | Everything the bot's client was sent: chat, action bar, titles, boss bars, scoreboard, health, effects, open menu |\n| `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 |\n| `bot_view` | Live localhost viewer for one bot — the world, or the menu it has open |\n\n### Scenario steps\n\n`bot_run_scenario` scripts a whole test from these steps — a failure reports the failing step and\nwhat the server was doing at that moment:\n\n| Category | Step | What it does |\n|---|---|---|\n| **World & movement** | `spawn` | Connect the bot and wait until it is standing in the world |\n| | `despawn` | Disconnect the bot |\n| | `move_to` | Walk there through real physics — pressure plates and move listeners fire; `teleport` mode for setup |\n| | `look_at` | Face a block or position |\n| | `jump` | Jump |\n| | `sneak` | Start or stop sneaking |\n| | `sprint` | Start or stop sprinting |\n| **Blocks & items** | `break_block` | Break a block, through real digging |\n| | `place_block` | Place a block from the hand |\n| | `use_block` | Right-click a block — buttons, doors, chests |\n| | `hold_item` | Put an item into the main hand |\n| | `drop_item` | Drop the held item |\n| **Interaction** | `use_entity` | Right-click an entity — the way a shop or quest NPC is actually triggered |\n| | `attack_entity` | Attack an entity |\n| | `click_slot` | Click a slot in the open menu or GUI |\n| | `close_menu` | Close the open menu |\n| | `chat` | Send a chat message as the bot |\n| | `command` | Send a command as the bot, permissions and all |\n| | `console` | Run a console command mid-scenario |\n| **Waiting** | `wait_for` | Block until a condition holds — every `wait_for` condition is available as a step |\n| **Assertions** | `assert_block` | Assert what a block is |\n| | `assert_player` | Assert a player's live state — position, game mode, op, health |\n| | `assert_event` | Assert that an event fired on the server |\n| | `assert_inventory` | Assert the slots of the open GUI or an inventory |\n| | `assert_message` | Assert what the bot's client was told — chat, action bar, title |\n| | `assert_reachable` | Assert a position can actually be walked to |\n\nHow the three pieces fit together, what every tool and step accepts, and an example scenario are in\n[docs/reference.md](docs/reference.md).\n\n## Version support\n\n| Minecraft version | Windows | Linux | macOS | Status |\n|---|:---:|:---:|:---:|---|\n| 1.18 – 1.20.6 | 🟡 | 🟡 | 🟡 | Planned; below the current agent floor (1.21) |\n| **1.21 – 1.21.11** | **🟢** | **🟢** | **🟢** | **Supported and live-tested** |\n| **26.1 – 26.1.2** | **🟢** | **🟢** | **🟢** | **Supported and live-tested**; the server needs Java 25 |\n| 26.2 and later | 🟡 | 🟡 | 🟡 | Released; each needs a compatibility run before it is added |\n\n#### Runner support by operating system\n\n| Operating system | Node source runner | Native runner asset | Meaning |\n|---|:---:|:---:|---|\n| **Windows x64** | 🟢 | 🟢 | Published, and the platform the matrix is run on |\n| **Linux x64 / arm64** | 🟢 | 🟢 | Published since 3.0.0 |\n| **macOS Intel / Apple Silicon** | 🟢 | 🟢 | Published since 3.0.0, ad-hoc signed |\n\n**Legend:** 🟢 supported · 🟡 planned or requires the stated runtime · 🔴 unsupported.\n\nRequirements, where each claim comes from, and how the version matrix is run are in\n[docs/reference.md](docs/reference.md#requirements).\n\n## Setup\n\n**1. Install the plugin** — download `VitaminMCP.jar` from the\n[latest release](https://github.com/Backas03/VitaminMCP/releases/latest) (or from\n[Modrinth](https://modrinth.com/plugin/vitaminmcp)), drop it into `plugins/`, and start the server.\n\n**2. Add the MCP server to your AI client** — it runs on your machine, not on the server:\n\n*Claude Code*\n\n```\nclaude mcp add vitaminmcp -- npx -y vitaminmcp\n```\n\n*Claude Desktop, Cursor, or any client with a JSON MCP config:*\n\n```json\n{\n  \"mcpServers\": {\n    \"vitaminmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"vitaminmcp\"]\n    }\n  }\n}\n```\n\nIt is also on the [official MCP registry](https://registry.modelcontextprotocol.io) as\n`io.github.Backas03/vitaminmcp`, so clients with a registry catalogue can add it from there.\n\n**3. Let the agent wire itself up** — ask it to run the `setup` prompt (in Claude Code:\n`/mcp__vitaminmcp__setup`). It finds the running server, checks the plugin, and connects.\n\nThat is enough for a server on this machine. The Claude Code plugin (which also brings the testing\nskill), other clients, installing from the jars, `config.yml` defaults, bot setup, and reaching a\nserver behind SSH or TLS are all in [INSTALL.md](INSTALL.md).\n\nFull installation and usage docs: **[backas03.github.io/VitaminMCP](https://backas03.github.io/VitaminMCP/)**\n— every tool, scenario runs, multi-server sessions, and remote-server setup are covered in\n[docs/usage.md](docs/usage.md).\n\n## Contributing and building\n\nContribution rules are in [CONTRIBUTING.md](CONTRIBUTING.md), building from source in\n[docs/reference.md](docs/reference.md#building-from-source), and release steps in\n[docs/publishing.md](docs/publishing.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE). The third-party code bundled in the jars, and its licenses, are\nlisted in [docs/reference.md](docs/reference.md#license).\n",
  "bytes": 8166,
  "sha": "084065fa8de4e4e03a1c1d6e1cc081423f57730f78285a68375811e864b05539",
  "repo_slug": "backas03/vitaminmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_backas03_vitaminmcp_299a6adb/readme"
}