VitaminMCP

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

VitaminMCP

Minecraft automation testing MCP server plugin for AI agents.

VitaminMCP is a Paper/Purpur server plugin. Drop VitaminMCP.jar into plugins/, start the server, and it opens an MCP endpoint from inside the running server — so an AI agent can drive that server and read back what happened, while real bot clients connect to it over the Minecraft protocol.

Nothing about the plugin you are testing changes. No test framework to adopt, no source to instrument, no harness to compile against, no mock server standing in for a real one: the plugin under test runs on a real server through its real lifecycle, and VitaminMCP watches it from the next plugin slot over. Which also means it works on plugins you did not write — anything already installed is testable.

Drive a real Minecraft server and real players through MCP tools, and run end-to-end plugin tests without opening the game.

Spawn and control test players — real protocol clients, not mock Player objects
Execute commands as the console or as a player
Open, read, click and assert on inventories and plugin GUIs
Right-click NPCs and villagers, the way a shop or quest giver is actually triggered
Move players, break and use blocks, chat
Wait for events and conditions instead of sleeping
Assert on blocks, players, events, inventories and the messages a player received
Read the player's whole screen: menus, chat, action bar, titles, boss bars, scoreboard
Read live server state: events, logs, exceptions, permissions
Drive several servers at once — one session per backend of a BungeeCord network, bots staying connected across all of them
Paper / Purpur 1.21 through 1.21.11, from one install — the runner works out which protocol the server speaks and adapts

Full usage is in docs/usage.md. Contribution rules are in CONTRIBUTING.md, and release steps are in docs/publishing.md.

How it fits together

Three jars, in three different places. Only the first is a Minecraft plugin.

text

  your MCP client (Claude Code, ...)
        |
        |  stdio
        v
  mcp-server.jar ---- HTTP(S) + token ---->  VitaminMCP.jar  <- the plugin, inside your server
        |                                    sees events, logs, exceptions, live state
        |  spawns
        v
  Node runner -------- Minecraft protocol ->  the same server, on :25565
                                             sees what a player's client was actually sent

	Runs	Role
`VitaminMCP.jar`	in the server, as a plugin	Listens to every event, taps the log, and serves an authenticated MCP endpoint. The only piece with a view of server internals
`mcp-server.jar`	on your machine, as a child of your MCP client	Speaks stdio to the client and HTTP to the plugin, and owns the bots
`runner.mjs` or a platform `bot-runner-*` asset	on your machine, as a child of `mcp-server`	Connects real clients over the real protocol — login, packets, GUIs and all

The plugin sees server-side events, logs, permissions and state; the Node runner sees what a real client receives. Read-only mode is the default, and bots are optional.

Example

Ask the agent to test a plugin, or pass a scenario to bot_run_scenario:

config.json

[
  {"action":"spawn", "bot":"Tester1"},
  {"action":"command", "bot":"Tester1", "command":"shop"},
  {"action":"wait_for", "condition":"inventory_open", "name":"Tester1", "title":"Shop"},
  {"action":"assert_inventory", "bot":"Tester1", "slots":[
    {"slot":11, "material":"DIAMOND_SWORD", "name":"Diamond Sword"}
  ]}
]

Tools

Two groups. Session tools live in mcp-server and are always present. Agent tools are proxied from the plugin, so which ones exist is decided by the server you connected to — session_start returns their real definitions in agentTools.

Connection


`session_start`	Connect to a server and its agent. Every other tool needs it. Several sessions can be open at once — one per backend of a proxied network
`session_reset`	Disconnect every bot, keeping the connection. Use between independent tests. World state is not rolled back. `close: true` ends the session instead

Players


`bot_spawn`	Connect a bot and wait until it is standing in the world. UUID derives from the name
`bot_inspect`	What the bot's client was actually sent: menu contents, messages (chat, action bar, title, subtitle) with the millisecond each arrived and a cursor to read only what came after an action, boss bars, sidebar scoreboard, health, food, experience and active effects
`bot_view`	Open a localhost-only live world or inventory view for a bot. The inventory view needs nothing extra; the world view downloads an optional asset the first time it is asked for, published for Windows x64
`bot_run_scenario`	Run a whole scenario. Stops at the first failure with evidence attached

Server


`server_info`	Version, TPS, players online, installed plugins, capture statistics
`command_exec`	Run a command as the console or as a player, vanilla commands included. Changes the server — absent entirely unless `read-only: false`. When nothing takes the command it says why, rather than only that it did not

World and state


`state_query` `kind="player"`	Position, gamemode, op, IP, and any permission nodes you name
`state_query` `kind="block"`	The block at a coordinate
`state_query` `kind="inventory"`	The menu a player has open — the only place a plugin GUI's contents exist

Events and logs


`events_summary`	Counts by event type. Call this before `events_query` — it stays small however busy the server is
`events_query`	Individual events, filtered by type and player, paged by cursor
`logs_query`	Logs by minimum severity and regular expression
`exceptions_recent`	Distinct exceptions with occurrence counts and first-seen times. Pass `hash` for a stack trace

Waiting

wait_for blocks until a condition holds, checked every tick inside the server.

Condition
`inventory_open`	a menu opened, optionally matching a title
`inventory_contains`	an item reached a slot — for GUIs filled after they open
`event`	an event fired, optionally for one player
`player_online` / `player_offline`	a player joined or left
`player_state`	`online` / `gameMode` / `op` reached a value
`player_near`	a player came within a radius
`block_is` / `block_is_not`	a block became, or stopped being, a material
`log_matches`	a log line matched a regex — for async work that changes nothing observable
`ticks`	the server advanced N ticks

There is no sleep, and there will not be one. A fixed wait is a guess about timing that is right on an idle server and wrong on a busy one — that is the entire mechanism by which flaky tests are made. On timeout, wait_for returns the events and logs from that moment.

Actions — scenario steps

Available inside bot_run_scenario.


`spawn` / `despawn`	connect or disconnect a bot
`move_to`	walk to coordinates by default; use `mode: "teleport"` for fast setup placement. Optional `timeoutMillis` distinguishes a sealed route from a walk that did not arrive in time
`break_block` / `use_block`	break, or right-click a block — `use_block` is how you open a chest
`use_entity`	right-click an NPC, villager or armour stand, named by the coordinates it stands at
`attack_entity`	left-click the nearest NPC, mob or armour stand at coordinates
`hold_item` / `drop_item`	select a hotbar slot, or drop the held item/one held item
`place_block`	place the held item against a block face
`jump` / `sneak` / `sprint`	perform one jump, or set the movement state on/off
`look_at`	look at world coordinates directly
`assert_reachable`	ask whether a loaded path exists without moving; set `reachable: false` for sealed-region assertions
`click_slot`	click a slot: `left`, `right`, `shift_left`, `shift_right`
`close_menu`	close the open menu
`chat` / `command`	say something, or run a command as the bot
`console`	run a command as the console
`wait_for`	any condition above

Assertions — scenario steps

Verification is the point, so this is where the surface is widest.

	Checks
`assert_inventory`	per slot: `material`, `name`, `amount`, `lore`, `customModelData`, `modelDataString`, `empty` — plus the menu's `title` and `size`
`assert_player`	`online`, `gameMode`, `op`. Waits rather than reads, because `/op` resolves asynchronously
`assert_block`	the material at a coordinate
`assert_event`	an event fired, optionally for one player, since the scenario began
`assert_message`	the server told this bot something containing a string

Use bot_inspect for messages, screen state and effects; use state_query for server state. Pass proxied parameters flat at the top level. Full parameters are in docs/usage.md.

Requirements

These are the requirements for using a prebuilt release:


Minecraft server	Paper 1.21 or later (Purpur and other Paper forks work)
Java	21, for the Paper server and local MCP server
Node	18.17 or later, for `npx`

Version support

Minecraft version	Windows	Linux	macOS	Status
1.18 – 1.20.6	🔴	🔴	🔴	Below the Paper agent floor
1.21 – 1.21.11	🟢	🟢	🟢	Supported and live-tested
26.1, 26.2 and later	🟡	🟡	🟡	Released; each needs a compatibility run before it is added

Runner support by operating system

Read the full README on GitHub →

Related MCP Servers

View all in Gaming View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about VitaminMCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "vitaminmcp": { "command": "npx", "args": ["-y", "VitaminMCP"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/vitaminmcp-2?style=directory)](https://allmcps.com/mcp/vitaminmcp-2)

HTML Embed

<a href="https://allmcps.com/mcp/vitaminmcp-2"><img src="https://allmcps.com/api/badge/vitaminmcp-2?style=directory" alt="VitaminMCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryGaming

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🎮 Gaming →Best MCP servers for Gaming →Alternatives to VitaminMCP →Install in Claude Desktop Install in Cursor Install in VS Code

VitaminMCP

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

VitaminMCP

Minecraft automation testing MCP server plugin for AI agents.

Drive a real Minecraft server and real players through MCP tools, and run end-to-end plugin tests without opening the game.

Spawn and control test players — real protocol clients, not mock Player objects
Execute commands as the console or as a player
Open, read, click and assert on inventories and plugin GUIs
Right-click NPCs and villagers, the way a shop or quest giver is actually triggered
Move players, break and use blocks, chat
Wait for events and conditions instead of sleeping
Assert on blocks, players, events, inventories and the messages a player received
Read the player's whole screen: menus, chat, action bar, titles, boss bars, scoreboard
Read live server state: events, logs, exceptions, permissions
Drive several servers at once — one session per backend of a BungeeCord network, bots staying connected across all of them
Paper / Purpur 1.21 through 1.21.11, from one install — the runner works out which protocol the server speaks and adapts

Full usage is in docs/usage.md. Contribution rules are in CONTRIBUTING.md, and release steps are in docs/publishing.md.

How it fits together

Three jars, in three different places. Only the first is a Minecraft plugin.

text

  your MCP client (Claude Code, ...)
        |
        |  stdio
        v
  mcp-server.jar ---- HTTP(S) + token ---->  VitaminMCP.jar  <- the plugin, inside your server
        |                                    sees events, logs, exceptions, live state
        |  spawns
        v
  Node runner -------- Minecraft protocol ->  the same server, on :25565
                                             sees what a player's client was actually sent

	Runs	Role
`VitaminMCP.jar`	in the server, as a plugin	Listens to every event, taps the log, and serves an authenticated MCP endpoint. The only piece with a view of server internals
`mcp-server.jar`	on your machine, as a child of your MCP client	Speaks stdio to the client and HTTP to the plugin, and owns the bots
`runner.mjs` or a platform `bot-runner-*` asset	on your machine, as a child of `mcp-server`	Connects real clients over the real protocol — login, packets, GUIs and all

The plugin sees server-side events, logs, permissions and state; the Node runner sees what a real client receives. Read-only mode is the default, and bots are optional.

Example

Ask the agent to test a plugin, or pass a scenario to bot_run_scenario:

config.json

[
  {"action":"spawn", "bot":"Tester1"},
  {"action":"command", "bot":"Tester1", "command":"shop"},
  {"action":"wait_for", "condition":"inventory_open", "name":"Tester1", "title":"Shop"},
  {"action":"assert_inventory", "bot":"Tester1", "slots":[
    {"slot":11, "material":"DIAMOND_SWORD", "name":"Diamond Sword"}
  ]}
]

Tools

Connection


`session_start`	Connect to a server and its agent. Every other tool needs it. Several sessions can be open at once — one per backend of a proxied network
`session_reset`	Disconnect every bot, keeping the connection. Use between independent tests. World state is not rolled back. `close: true` ends the session instead

Players


`bot_spawn`	Connect a bot and wait until it is standing in the world. UUID derives from the name
`bot_inspect`	What the bot's client was actually sent: menu contents, messages (chat, action bar, title, subtitle) with the millisecond each arrived and a cursor to read only what came after an action, boss bars, sidebar scoreboard, health, food, experience and active effects
`bot_view`	Open a localhost-only live world or inventory view for a bot. The inventory view needs nothing extra; the world view downloads an optional asset the first time it is asked for, published for Windows x64
`bot_run_scenario`	Run a whole scenario. Stops at the first failure with evidence attached

Server


`server_info`	Version, TPS, players online, installed plugins, capture statistics
`command_exec`	Run a command as the console or as a player, vanilla commands included. Changes the server — absent entirely unless `read-only: false`. When nothing takes the command it says why, rather than only that it did not

World and state


`state_query` `kind="player"`	Position, gamemode, op, IP, and any permission nodes you name
`state_query` `kind="block"`	The block at a coordinate
`state_query` `kind="inventory"`	The menu a player has open — the only place a plugin GUI's contents exist

Events and logs


`events_summary`	Counts by event type. Call this before `events_query` — it stays small however busy the server is
`events_query`	Individual events, filtered by type and player, paged by cursor
`logs_query`	Logs by minimum severity and regular expression
`exceptions_recent`	Distinct exceptions with occurrence counts and first-seen times. Pass `hash` for a stack trace

Waiting

wait_for blocks until a condition holds, checked every tick inside the server.

Condition
`inventory_open`	a menu opened, optionally matching a title
`inventory_contains`	an item reached a slot — for GUIs filled after they open
`event`	an event fired, optionally for one player
`player_online` / `player_offline`	a player joined or left
`player_state`	`online` / `gameMode` / `op` reached a value
`player_near`	a player came within a radius
`block_is` / `block_is_not`	a block became, or stopped being, a material
`log_matches`	a log line matched a regex — for async work that changes nothing observable
`ticks`	the server advanced N ticks

Actions — scenario steps

Available inside bot_run_scenario.


`spawn` / `despawn`	connect or disconnect a bot
`move_to`	walk to coordinates by default; use `mode: "teleport"` for fast setup placement. Optional `timeoutMillis` distinguishes a sealed route from a walk that did not arrive in time
`break_block` / `use_block`	break, or right-click a block — `use_block` is how you open a chest
`use_entity`	right-click an NPC, villager or armour stand, named by the coordinates it stands at
`attack_entity`	left-click the nearest NPC, mob or armour stand at coordinates
`hold_item` / `drop_item`	select a hotbar slot, or drop the held item/one held item
`place_block`	place the held item against a block face
`jump` / `sneak` / `sprint`	perform one jump, or set the movement state on/off
`look_at`	look at world coordinates directly
`assert_reachable`	ask whether a loaded path exists without moving; set `reachable: false` for sealed-region assertions
`click_slot`	click a slot: `left`, `right`, `shift_left`, `shift_right`
`close_menu`	close the open menu
`chat` / `command`	say something, or run a command as the bot
`console`	run a command as the console
`wait_for`	any condition above

Assertions — scenario steps

Verification is the point, so this is where the surface is widest.

	Checks
`assert_inventory`	per slot: `material`, `name`, `amount`, `lore`, `customModelData`, `modelDataString`, `empty` — plus the menu's `title` and `size`
`assert_player`	`online`, `gameMode`, `op`. Waits rather than reads, because `/op` resolves asynchronously
`assert_block`	the material at a coordinate
`assert_event`	an event fired, optionally for one player, since the scenario began
`assert_message`	the server told this bot something containing a string

Use bot_inspect for messages, screen state and effects; use state_query for server state. Pass proxied parameters flat at the top level. Full parameters are in docs/usage.md.

Requirements

These are the requirements for using a prebuilt release:


Minecraft server	Paper 1.21 or later (Purpur and other Paper forks work)
Java	21, for the Paper server and local MCP server
Node	18.17 or later, for `npx`

Version support

Minecraft version	Windows	Linux	macOS	Status
1.18 – 1.20.6	🔴	🔴	🔴	Below the Paper agent floor
1.21 – 1.21.11	🟢	🟢	🟢	Supported and live-tested
26.1, 26.2 and later	🟡	🟡	🟡	Released; each needs a compatibility run before it is added

Runner support by operating system

Read the full README on GitHub →

Related MCP Servers

View all in Gaming View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about VitaminMCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "vitaminmcp": { "command": "npx", "args": ["-y", "VitaminMCP"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/vitaminmcp-2?style=directory)](https://allmcps.com/mcp/vitaminmcp-2)

HTML Embed

<a href="https://allmcps.com/mcp/vitaminmcp-2"><img src="https://allmcps.com/api/badge/vitaminmcp-2?style=directory" alt="VitaminMCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryGaming

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🎮 Gaming →Best MCP servers for Gaming →Alternatives to VitaminMCP →Install in Claude Desktop Install in Cursor Install in VS Code