mcsvr

mcsvr is a cross-platform Minecraft server manager for Linux and Windows. It combines a full-screen interactive control panel with a hidden local daemon that owns server processes.

Status: 0.3.4 release. The lifecycle and interactive control panel are implemented end to end, but production deployment still requires staging with your exact game version, loader, mods, backup volume, and operating-system service account.

Features

• Vanilla, stable Paper, Fabric, Forge, and NeoForge installation from upstream metadata, including pinned loader versions
• Multiple named Minecraft instances and managed Eclipse Temurin runtimes
• Cross-platform daemon, graceful stops, bounded crash restarts, and autostart
• Keyboard-and-mouse control panel; routine management requires no commands
• Recent/followed logs, interactive console, and one-shot command delivery
• Online backups, retention, SHA-256 validation, safety snapshots, and staged restore
• Online/offline OP management and delegated command allow/deny rules
• Curated one-click anti-cheat setup, plus verified manual artifact installation
• Compatible Modrinth mod/plugin discovery, dependency installation, updates, removal, and visibility into manually installed JARs
• SQLite player directory populated from usercache and join/leave events
• systemd and Windows Service Control Manager integration
• Recoverable server deletion that moves instances and backups into local trash

One-click install

Download or extract the release bundle, then:

Windows: double-click install.cmd. It finds or installs Python 3.12, creates an isolated environment, installs mcsvr, adds it to the user PATH, creates a Start Menu shortcut, and opens the control panel. The daemon starts silently with no second console window.

Linux: run bash install.sh once. It creates an isolated environment, adds a launcher under ~/.local/bin, adds an application-menu shortcut, and opens the control panel. The daemon detaches and has no interactive interface.

The installers update the application without overwriting Minecraft instances, configuration, or backups. The uninstall scripts retain server data by default.

Manual install

Python 3.11 or newer is required.

python -m venv .venv
# Linux
. .venv/bin/activate
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install .

Set a writable data location when running without a dedicated OS account:

# Linux
export MCSVR_HOME="$HOME/.local/share/mcsvr"
# Windows PowerShell
$env:MCSVR_HOME="$env:LOCALAPPDATA\mcsvr"

Then run mcsvr with no arguments to open the full-screen control panel.

Interactive control panel

The default interface is keyboard and mouse friendly. No management commands need to be memorized:

• N opens the guided server wizard.
• Arrow keys select a server.
• S starts and X gracefully stops it.
• T restarts it and E opens server configuration.
• C opens the live console.
• M opens compatible mods or plugins.
• B opens backups.
• A opens OP, command-permission, and anti-cheat administration.
• D safely deletes a stopped server by moving it to recoverable trash.
• Sidebar buttons expose the same actions for mouse users.

The interface automatically responds to terminal resizing. Wide windows use a sidebar and multi-column forms, medium windows reduce spacing, narrow windows move navigation above the dashboard and stack form fields, and short windows collapse nonessential summaries into a compact scrollable toolbar.

The setup wizard presents selectable recent Minecraft versions and controls for server software, min/max memory, seed, game mode, difficulty, player limit, world type, distances, spawn protection, whitelist, PvP, hardcore, flight, command blocks, and port. Values may be left automatic where appropriate. It:

• selects the latest stable Minecraft release unless another is requested;
• chooses Paper, Fabric, or Vanilla from the selected play style;
• detects or downloads the required Eclipse Temurin Java release;
• assigns an unused Minecraft port;
• sizes the heap from installed physical memory;
• configures view and simulation distances;
• enables online mode and keeps RCON/query disabled;
• enables autostart, bounded crash recovery, and six-hour backups;
• retains 14 backups for up to 30 days.

The Configure panel changes Java, memory, port, gameplay properties, automatic backups, autostart, and crash recovery after creation.

Mods, plugins, and anti-cheat

The Mods / plugins panel searches Modrinth with the instance's exact Minecraft version and loader. It selects a compatible stable release, verifies the upstream SHA-512/SHA-1 hash, installs required dependencies, tracks managed versions, updates them together, and moves removed JARs into a recovery folder. Existing manually installed JARs remain visible as unmanaged content.

The Administration panel offers popular compatible anti-cheat selections such as Grim, Themis, and TruthfulAC when supported. Compatibility is resolved at install time. Always review a project's publisher, license, release notes, and server impact before deploying it.

Optional automation interface

The installed shortcut and a plain mcsvr launch show only the control panel. The command interface below remains available for scripted administration and service setup; it is not needed for normal use.

Automation examples

mcsvr java install 21
mcsvr instance create survival --minecraft 1.21.1 --loader paper --java temurin-21 --memory-max 4096 --accept-eula
mcsvr instance start survival
mcsvr logs survival --follow

The same automatic setup is also available without the visual wizard:

mcsvr instance quick-create survival --profile simple --accept-eula

The accept-eula flag records acceptance in that instance only. Read the Minecraft EULA first.

Send commands or open a persistent prompt:

mcsvr command survival say Server maintenance in 10 minutes
mcsvr console survival

Create and restore backups:

mcsvr backup create survival
mcsvr backup list survival
mcsvr backup restore survival 20260811T080000Z-a1b2c3d4

Restore requires a stopped instance and makes a safety backup unless --no-safety-backup is explicitly supplied.

Versions and configuration

Instances store game, loader, and Java versions independently. Use --loader-version to pin Fabric, Forge, NeoForge, or Paper.

mcsvr java install 17 --name legacy-java
mcsvr instance create modded --minecraft 1.20.1 --loader forge --loader-version 47.4.0 --java legacy-java --accept-eula

Downloads use HTTPS and upstream checksums where providers publish them. Mojang artifacts use SHA-1 from Mojang metadata; Paper and Temurin use SHA-256; user-supplied plugin/mod downloads always require SHA-256.

The default data directory is %LOCALAPPDATA%\mcsvr on Windows, /var/lib/mcsvr for root on Linux, and $XDG_DATA_HOME/mcsvr for an unprivileged Linux user. Windows service deployments should explicitly use --home C:\ProgramData\mcsvr. Override any default with --home or MCSVR_HOME.

The generated config.json controls the local daemon and anti-cheat log rules. See config.example.json. Restart the daemon after edits. The RPC endpoint rejects non-loopback addresses.

mcsvr instance set-property survival difficulty hard
mcsvr instance set-property survival white-list true

Operators and permissions

When running, OP changes use the Minecraft console. When stopped, mcsvr edits ops.json atomically and requires a UUID.

mcsvr op add survival Alex
mcsvr op add survival Alex --uuid 01234567-89ab-cdef-0123-456789abcdef --level 3
mcsvr op remove survival Alex
mcsvr permission set survival moderator "kick *" allow
mcsvr permission set survival moderator stop deny
mcsvr command survival --actor moderator kick Griefer

Host rules protect commands submitted through mcsvr. In-game permissions must use Minecraft OP levels or a loader-specific permission plugin.

Anti-cheat

mcsvr installs a plugin/mod only from HTTPS plus an expected SHA-256:

mcsvr anticheat install survival https://example.invalid/anticheat.jar --sha256 HASH

The optional log engine aggregates plugin alerts, audits detections, and can send a templated command after a threshold. A host manager cannot reliably detect physics cheats from logs alone; use a maintained game-aware plugin/mod as the primary defense.

OS service

Install the package system-wide first.

# Linux
sudo mcsvr --home /var/lib/mcsvr service install --user mcsvr
sudo systemctl start mcsvr

# Elevated Windows PowerShell
mcsvr --home C:\ProgramData\mcsvr service install
sc.exe start mcsvr

Production checklist

• Use a dedicated, non-administrator OS account with narrow filesystem access.
• Put backups on another volume and copy tested archives off-host.
• Keep online-mode enabled, RCON disabled unless secured, and firewall ports.
• Test restores and upgrades on a cloned instance before production.
• Pin loader/plugin/mod builds and review releases before upgrades.
• Leave memory for the OS, filesystem cache, backups, and native allocations.
• Monitor audit_log, anti_cheat_events, disk space, and restarts.
• Never install plugins or mods without verifying publisher and checksum.

Development

python -m pip install -e ".[dev]"
pytest
ruff check .

See architecture and security.