Skip to content
MCP server

VitaminMCP

MCP server that lets AI agents test Minecraft Paper plugins on a live server with bot

Runs locallyActively maintainedStatus and history

The repository was last updated 29 days ago and is published under MIT.

Install
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 vitaminmcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "npx",
      "args": [
        "-y",
        "vitaminmcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "npx",
      "args": [
        "-y",
        "vitaminmcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers