mc-server-wrapper

A small utility that wraps a Java Minecraft server process and exposes HTTP APIs that let you interact with that server.

Built to wrap a vanilla Minecraft server — not servers with Fabric or Forge, for instance.

If you plan to run a server with players you don't trust: please read this disclaimer about API abuse and access management.

Installation

1. Get a mc-server-wrapper binary
   • Either by downloading one of the prepared ones in this repo's releases
   • Or by building this project from source
2. Follow the steps that you normally would to stand up a vanilla Minecraft server without this wrapper
   • If you've never done this before, there are plenty of resources online about this. Here are some to get you started
3. Move the mc-server-wrapper binary into the same directory as the server.jar file that Mojang provides
4. Make sure to configure your network or security group to allow incoming TCP traffic on whichever port you tell mc-server-wrapper to listen on (see more about configuration here)

Usage

Each time you want to launch the server, run the wrapper instead of running the server.jar file that Mojang provides.

# Instead of something like:
# $ java [...] -jar server.jar [...]
# Run this instead:
./mc-server-wrapper

By default, mc-server-wrapper will only write messages to stdout that the Minecraft server produces. If you'd like to see log messages that have more info about events and errors, set the RUST_LOG environment variable.

# Either set it permanently:
echo "export RUST_LOG=mc_server_wrapper" >> ~/.bashrc # (or ~/.zshrc, or whatever else you use)
source ~/.bashrc # (or ~/.zshrc, or whatever)
./mc-server-wrapper
# Or control it on a case-by-case basis:
RUST_LOG=mc_server_wrapper ./mc-server-wrapper

Configuration

mc-server-wrapper loads configs from a .yaml file on startup. If a config file doesn't exist, it creates one with some sensible defaults. Feel free to edit the file and change any of the values inside.

The config file lives in the appropriate place depending on your operating system. mc-server-wrapper uses the directories crate to find where that is. As of directories version 4.0, those locations are:

• Linux: /home/<your-username>/.config/mc-server-wrapper/config.yaml
• macOS: /Users/<your-username>/Library/Application Support/com.nchaloult.mc-server-wrapper/config.yaml
• Windows: C:\Users\<your-username>\AppData\Roaming\nchaloult\mc-server-wrapper\config\config.yaml

Here's a sample config.yaml file:

---
# Port that mc-server-wrapper listens for HTTP requests on.
port: 6969
# Path to the server.jar file provided my Mojang.
#
# Can either be relative to the `mc-server-wrapper` binary, or an absolute path.
server_jar_path: server.jar
# The max size (in megabytes) for the Minecraft server process's memory
# allocation buffer on the JVM.
#
# This number is passed into the `-Xmx` option when spawning the server process.
max_memory_buffer_size: 2048

Command-Line Functionality

Normally, the primary way to interact with a vanilla Minecraft server is by entering commands into an interactive process that the server.jar spawns. mc-server-wrapper doesn't compromise this functionality — it captures user input and passes it to that process's stdin. If you'd like, you can interact with the Minecraft server as if the wrapper weren't there.

HTTP APIs

• GET /list-players: Get a list of the usernames of all players who are currently logged in
• GET /make-world-backup: Gracefully shut down the Minecraft server, create a compressed tarball of the world/ directory, and restart it
• GET /stop: Gracefully shut down the Minecraft server, and stop listening for more incoming HTTP requests

(A lot of these GET APIs aren't exactly RESTful. They're more like remote procedure calls, really. That's fine with me, I'm not shooting for a great API design with this project.)

A Note about API Abuse and Access Management

Wait, can't anyone hit the API endpoints that mc-server-wrapper exposes?

Yes, they can!

If you stand up a Minecraft server, give out its address or domain name, and players know that you're using this wrapper, there's nothing stopping them from finding the port it's listening for requests on and hitting its endpoints. This wrapper doesn't protect them with rate limiting, some kind of authentication mechanism, or anything else.

I worked on this project to learn more about Rust, and to build something that made mine and my friends' lives easier while maintaining servers that we play on together. If there were 25 hours in a day, I'd love to get around to addressing these issues. For now, though, please be aware that these problems exist if you want to use this wrapper.