Server statistics via the built-in Minecraft Query interface
- Player count (online/max)
- Player list
- MOTD
- Server version
- Ping
Per-world performance metrics (via RCON, optional)
- TPS (ticks per second)
- Tick time (ms)
Automatic service discovery for each server and its worlds
Metrics for graphs and performance analysis in Checkmk
Error handling with fail counter to suppress short outages

Requirements

A running Checkmk installation (v2.x or newer recommended)
Minecraft server with Query interface enabled (default on most servers)
Optional: RCON enabled if you want per-world TPS and tick-time monitoring

Currently, only NeoForge has been tested for RCON TPS support. If you need other implementations or encounter problems, please open an issue.

Installation

Development setup

If you want to work on or test the plugin directly inside a Checkmk site, you have two options:

a) Release an installed MKP If you already installed the package via mkp install, you can release it:

omd su <yoursite>
mkp release minecraft

This removes the MKP registration but leaves all contained files unpacked in the correct places under ~/local/..., so you can edit them directly:

Check plugin (agent-based): ~/local/lib/python3/cmk_addons/plugins/minecraft/agent_based/
Graph definitions: ~/local/lib/python3/cmk_addons/plugins/minecraft/graphing/
Agent plugin: ~/local/share/check_mk/agents/plugins/minecraft.py (Just for download purposes)

b) Clone the repository into your development site Alternatively, you can clone this repository directly into the site’s local directory:

omd su <yoursite>
cd ~/local/lib/python3/cmk_addons/plugins
git clone https://git.project-name-here.de/Project-Name-Here/checkmk-minecraft.git minecraft

# reload monitoring core
cmk -R

This way you can pull updates from git and test changes directly.

Installation from MKP (recommended)

For production use install the packaged MKP:

Download the .mkp file from the Releases or Checkmk Exchange.
Install it via GUI (Extension Packages) or via CLI:

omd su <yoursite>
mkp install minecraft-<version>.mkp
cmk -R

After installation, the agent plugin is available for download in the Checkmk GUI under Agents → Plugins. Install it on your Minecraft server as described in the next section.

Agent Plugin Setup

On the monitored Minecraft server host, place the agent plugin in /usr/lib/check_mk_agent/plugins/ and make it executable. It will then be executed automatically by the Checkmk agent. You can also run it manually for testing:

/usr/lib/check_mk_agent/plugins/minecraft.py

This will generate or update the minecraft.cfg file in the same directory.

Dependencies

Install the required Python dependencies on the monitored Minecraft server:

pip3 install mcstatus mcrcon --break-system-packages
apt install python3-typeguard

Usage

Run the agent plugin once on your Minecraft server. This will automatically generate a configuration file (minecraft_servers.json) in the same directory, which you can edit to define server addresses and optional RCON credentials.
Run a service discovery in Checkmk for the host.
You should now see:
- One service for the server itself (players, MOTD, version, ping).
- Additional services for each world (TPS and tick times, if RCON is enabled).
Graphs will be available for player counts, ping, TPS, and tick times.

Example Configuration

A simple automatically generated config (minecraft_servers.json):

[
  {
    "name": "default",
    "host": "127.0.0.1",
    "port": 25565,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  }
]

A valid configuration with multiple servers:

[
  {
    "name": "server1",
    "host": "127.0.0.1",
    "port": 25565,
    "rcon": true,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": "xxxxxxxxxxx"
  },
  {
    "name": "server2",
    "host": "127.0.0.1",
    "port": 25566,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  },
  {
    "name": "server3",
    "host": "127.0.0.1",
    "port": 25567,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  },
  {
    "name": "server4",
    "host": "127.0.0.1",
    "port": 25568,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  }
]

Error Handling

Both Query and RCON errors are checked.
A fail counter prevents false alarms by tolerating short outages.
After 5 consecutive failures, the check switches to CRIT.

Development & Contributions

Currently tested only with NeoForge for RCON TPS values.
Support for additional server implementations may be added later.
If you need support for another implementation or encounter issues, please open an issue.

Contributions via pull requests are welcome!

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

README.md Unescape Escape

Checkmk Minecraft Monitoring Plugin

Features