# VitaminMCP

> VitaminMCP is an open-source MCP server for developer tools. MCP server that lets AI agents test Minecraft Paper plugins on a live server with bot. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, CLI, Linux, macOS, Windows, self-hosted
- **Repository:** https://github.com/backas03/vitaminmcp
- **GitHub stars:** 2
- **License:** MIT
- **MCP Registry name:** io.github.Backas03/vitaminmcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add vitaminmcp -- npx -y vitaminmcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "vitaminmcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "vitaminmcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

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

## Alternatives

- [MCP Server](https://ai-powered.com/mcp/mcp-server-mweo0sk4): MCP Server is an MCP server for developer tools.
- [Api Test MCP](https://ai-powered.com/mcp/api-test-mcp): Api Test MCP is an open-source MCP server for developer tools.
- [MCP Server Commands](https://ai-powered.com/mcp/mcp-server-commands): MCP Server Commands is an open-source MCP server for developer tools.
- [HeadlessMc](https://ai-powered.com/mcp/headlessmc): HeadlessMc is an open-source MCP server for games and play.
- [Mobai MCP](https://ai-powered.com/mcp/mobai-mcp): Mobai MCP is an open-source MCP server for developer tools.
- [Test Inventory](https://ai-powered.com/mcp/test-inventory): Test Inventory is an open-source MCP server for e-commerce.
- [Freshdeps MCP](https://ai-powered.com/mcp/freshdeps-mcp): Freshdeps MCP is a free MCP server for developer tools.
- [MCPProxy](https://ai-powered.com/mcp/mcpproxy): MCPProxy is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/vitaminmcp
