MCRun Maven Plugin

A Maven plugin that spins up a local Minecraft server for testing your plugin and automatically copies your built jar into the server's plugins folder, downloads the server software, and launches everything with a single command.

Requirements

• Java 21+ installed and available on your PATH
• An existing Minecraft plugin Maven project

Setup

1. Add the plugin repository

Maven needs to know where to download the plugin from. Add the following to your pom.xml inside the <pluginRepositories> block (create it if it doesn't exist):

<pluginRepositories>
    <pluginRepository>
        <id>strassburger</id>
        <url>https://maven.strassburger.org</url>
    </pluginRepository>
</pluginRepositories>

2. Add the plugin to your build

Add the following inside the <build><plugins> section of your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.strassburger</groupId>
            <artifactId>mcrun-maven-plugin</artifactId>
            <version>LATEST</version>
            <configuration>
                <mcVersion>1.21.4</mcVersion>
                <acceptEula>true</acceptEula>
            </configuration>
        </plugin>
    </plugins>
</build>

Note: Replace LATEST with the actual latest version, and set <mcVersion> to whichever Minecraft version you want to test against.

3. Start the server

mvn package mcrun:start

This will:

1. Build your plugin jar
2. Download the Minecraft server jar (if not already present)
3. Copy your plugin into the server's plugins/ folder
4. Start the server

---

Configuration Reference

All options go inside the <configuration> block of the plugin declaration.

Option	Default	Description
mcVersion	(required)	The Minecraft version to run, e.g. 1.21.4
acceptEula	false	Automatically accept the Minecraft EULA. By setting this to true you confirm your acceptance.
serverSoftware	paper	Server software to use. Supported values: paper, spigot
serverDirectory	./server	Folder where the server files will be created
serverJarName	server.jar	File name for the server jar inside serverDirectory
minMemory	512M	Minimum RAM allocated to the server (-Xms), e.g. 512M, 1G
maxMemory	2G	Maximum RAM allocated to the server (-Xmx), e.g. 2G, 4G
port	(Minecraft default)	Port the server listens on
remoteDebug	false	Enable remote JVM debugging so you can attach your IDE's debugger
debugPort	5005	Port used for remote debugging (only relevant if remoteDebug is true)
jvmArgs	(none)	Extra JVM flags passed to the server process
pluginJar	(your built jar)	Path to the plugin jar to deploy. You rarely need to change this

Full configuration example

<configuration>
    <mcVersion>1.21.4</mcVersion>
    <serverSoftware>paper</serverSoftware>
    <acceptEula>true</acceptEula>
    <memory>4G</memory>
    <port>25565</port>
    <remoteDebug>true</remoteDebug>
    <debugPort>5005</debugPort>
    <jvmArgs>
        <arg>-XX:+UseG1GC</arg>
        <arg>-XX:+ParallelRefProcEnabled</arg>
    </jvmArgs>
</configuration>

---

Tips

The server folder is reused between runs. The world, configuration files, and other data persist in ./server across restarts. Delete that folder if you want a completely fresh server.

The server jar is only downloaded once. If server.jar already exists in the server directory, it won't be re-downloaded.

Attaching a debugger. Enable <remoteDebug>true</remoteDebug>, then in your IDE add a "Remote JVM Debug" run configuration pointing to localhost:5005 (or whichever debugPort you set). Start the server first, then attach the debugger.

Stopping the server. Use the stop command inside the Minecraft server console, or press Ctrl+C in the terminal.

Using Spigot. When serverSoftware is set to spigot, the plugin downloads Spigot's BuildTools and compiles the jar locally rather than downloading a pre-built one. This can take several minutes on the first run, and requires Git to be installed on your system.