# VitaminMCP [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/Backas03/VitaminMCP-minecraft  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1060  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vitaminmcp

## Description
Test Minecraft plugins end to end: drive a real Paper server and real protocol bots.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "vitaminmcp": {
    "command": "npx",
    "args": ["-y","vitaminmcp"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/vitaminmcp/readme_