McPluginLab

A workbench for testing Minecraft plugins. Servers, proxies, plugin auto-deploy, bots and a game client in one app, driven from a desktop GUI, the command line or an AI agent.

⬇ Download the latest release

Why

Testing a plugin usually means juggling server folders, terminal windows, copied jars, proxy configs and a launcher, and repeating all of it whenever the version or the setup changes. McPluginLab (mpl) turns that into projects you start with one click:

• Servers in seconds. Paper, Purpur, Folia, Spigot (BuildTools), checksum-verified and cached. The EULA, offline mode and ports are set up for you.
• Proxies that configure themselves. Velocity, Waterfall or BungeeCord, with the server list, forwarding mode and secrets written on every start. Any server can be switched out of the network to run standalone.
• Live consoles. Real terminals with colors, tab completion and scrollback, embedded in the app or popped out into your own terminal. They keep running when the window closes.
• Plugin auto-deploy. Point a link at target/MyPlugin-*.jar; every build is copied to the right servers, old versions are removed and the servers restart.
• A database per project. MariaDB starts with the network and its connection is written into your plugins' configs.
• Bots and a real client. SoulFire bots and a built-in offline Minecraft launcher join your network automatically.
• The right Java, automatically. Each instance runs on the Java version it needs; missing JDKs are downloaded from Adoptium.
• Built for AI testing. An MCP server lets agents like Claude Code start the network, send commands, drive bots and wait for log lines, the same way you do.

Embedded console	Proxy network with standalone servers
Linked plugins	Adding a server, proxy, bots or client

Install

1. Make sure you have Linux x64 and Java 21 or newer (java -version). Servers, proxies, bots and the client get the Java they need automatically.
2. Download mpl-<version>.zip from the latest release (all versions are on the releases page).
3. Unzip it and start McPluginLab:

unzip mpl-1.0.1.zip
export PATH="$PWD/mpl-1.0.1/bin:$PATH"   # or add it to your shell profile
mpl desktop                               # optional: add McPluginLab to your application menu
mpl gui

To update, download the new release, replace the folder and run mpl desktop again. Your projects and servers are stored outside it (~/.local/share/mcpluginlab), so they are kept. To build from source instead, see Building from source.

Quick start

Create a project in the GUI, or do the same from the command line:

mpl project create skywars
mpl create skywars/proxy -t velocity
mpl create skywars/lobby -t paper -v 26.3
mpl create skywars/game1 -t paper -v 26.3
mpl create skywars/dev   -t paper -v 26.3 --standalone          # outside the proxy network
mpl create skywars/bots  -t soulfire --target proxy --count 3
mpl plugin add -P skywars SkyWars ~/SkyWars/target/SkyWars-*.jar

mpl up skywars                                                  # proxy and servers, then the bots
mpl bot skywars/bots -b Bot1 say /sw join --expect 'Bot1 issued server command' --expect-in skywars/lobby
mpl attach skywars/lobby                                        # Ctrl+] detaches
mpl down skywars

Now run mvn package in your plugin: the new jar is deployed and the servers restart by themselves.

Let an AI agent test your plugin

claude mcp add mpl -- /path/to/McPluginLab/cli/build/install/mpl/bin/mpl mcp

The agent gets tools such as start_project, deploy_plugins, send_command and bot_command with expect, wait_for_log and read_log with cursors, so it can run a full test loop: build, deploy, join with bots, trigger the feature and check the server log. A ready-made Claude Code skill (skills/mpl-plugin-test) drives that loop for you. See AI agents.

Documentation

Guide	Covers
Getting started	Install, first project, a tour of the GUI
Networks	Proxies, forwarding, standalone servers
Plugins	Linking build output and auto-deploy
Bots and clients	SoulFire bots and the built-in launcher
Databases	A MariaDB per project, wired into plugin configs
AI agents	The MCP server and an example test loop
CLI reference	Every mpl command
Architecture	Daemon, clients, files and the HTTP API

How it works

A small background daemon owns every process. The GUI, the CLI and the MCP server are thin clients that talk to it over a local HTTP and WebSocket API, so they all see the same live state. Servers keep running when you close the window, and you can watch a console in the app while an agent drives the same server through MCP.

flowchart LR
    GUI[Desktop GUI] --> D
    CLI[mpl CLI] --> D
    MCP[MCP server] --> D
    D[mpl daemon] --> S[Servers and proxies]
    D --> B[SoulFire bots]
    D --> C[Minecraft client]
    D --> P[Plugin watcher]

Loading

Supported software

Type	Versions from	Notes
Paper, Folia, Velocity, Waterfall	PaperMC API	sha256 verified
Purpur	Purpur API
Spigot	BuildTools	built once per version, then cached
BungeeCord	md_5 Jenkins
MariaDB	your installed mariadbd, else archive.mariadb.org	downloaded builds sha256 verified
SoulFire	GitHub releases	or your own SoulFireCLI jar
Minecraft client	Mojang manifest	offline accounts

Building from source

git clone https://github.com/l299l/mcpluginlab.git McPluginLab && cd McPluginLab
./gradlew installDist   # cli/build/install/mpl/bin/mpl
./gradlew test          # run the tests
./gradlew :cli:distZip  # release archive in cli/build/distributions

Rebuilding while mpl runs is safe: the daemon and the GUI run from a private copy of the jars. An idle daemon picks up a new build automatically; with instances running, the GUI offers to restart it.

License

McPluginLab is released under the MIT License.