Minecraft Web Manager

English | 中文

An MCDReforged plugin that serves a password-protected web dashboard for your Minecraft server: a live console, player management, online plugin and mod management, online editors for server.properties and MCDR's config.yml, mod-config editing and resource usage charts.

The dashboard is hosted by the plugin itself — no separate web server, no CDN, no frontend build step.

Version: 1.2.1
Requires: MCDReforged >=2.15.0, Python 3.10+
Python packages: fastapi, uvicorn[standard], python-multipart, psutil, ruamel-yaml

Features

Live console

Server output and in-game chat streamed over WebSocket; the last 1000 lines are replayed on (re)connect
Send both Minecraft commands and MCDR commands (!! prefix) — replies to things like !!MCDR status show up in the web console too
Choose the command channel: console (writes to the server's stdin) or RCON (returns the server's reply text)
↑ / ↓ browse command history; suggestions appear as you type
One-click start / stop / restart of the server
Always-visible overview strip: run state, player count, TPS/MSPT, uptime, Minecraft and MCDR versions, world name and seed

Live console

Player management

Roster: every player that has ever joined, merged from usercache.json, ops.json, whitelist.json, the ban lists and player save files — showing online state, IP, session length, last seen, dimension, coordinates and UUID. Online players and operators are pinned to the top. Detected Carpet fake players (bots) live in a separate "Bot management" table inside the same tab, collapsible and manually flaggable per row; the bot table is trimmed to player, status, session, last seen, dimension, position, UUID and actions (no IP/tags columns)
Per-player actions: op / deop, kick, ban, ban IP, add to / remove from whitelist
Whitelist: toggle enforcement, reload the list, add and remove entries
Operators: view, grant and revoke OP
Bans: ban and pardon players and IPs, with an optional reason

Player roster

Plugins & Mods

Plugins and mods share one tab, switched with two in-page sub-tabs: Plugins / Mods. Clicking the per-row "Config" button opens an animated modal where config files are edited.

Plugins

Plugin list: shows loaded, disabled and not-loaded plugins with their file states; loaded plugins can be disabled, disabled plugins can be enabled, and not-loaded plugins (e.g. those that failed to load at startup) can be loaded back with one click
Check updates / Update: uses the official MCDR plugin catalogue commands !!MCDR plugin checkupdate / !!MCDR plugin install -U -y. Results are shown as top-right toast notifications, plugins with updates are highlighted in yellow with the version change, plugins without updates no longer show the "Update" button, and a one-click "check all" is available. The outcome follows MCDR's actual output: success reports "Plugin updated", failures and timeouts say so explicitly and point to the live console; the panel itself is excluded from "update all"
Disable / Enable: calls !!MCDR plugin disable / enable; plugins are renamed to .disabled and restored per MCDR conventions. "Disable / Delete" are tucked into a per-row "⋯" menu so destructive actions never sit next to everyday ones
Config files: browse and edit files under each plugin's config/<plugin_id>/ folder in a modal; saving preserves the original encoding (UTF-8 / Latin-1), BOM and line endings. Binary files and files over 1 MiB are read-only, and .DS_Store files are filtered out
Delete: MCDR has no delete command, so the panel unloads a loaded plugin through MCDR first, then removes the plugin file; disabled / not-loaded files can be removed directly
Minecraft Web Manager itself cannot be disabled, deleted or updated from the panel, so the dashboard never takes itself down; reloading it is allowed — the panel briefly goes offline (~10 seconds) and comes back automatically, and the page's WebSocket reconnects on its own. To update the panel itself, run !!MCDR plugin install -U -y minecraft_web_manager followed by !!MCDR reload plugin minecraft_web_manager in the MCDR console
Management buttons are disabled while a plugin operation is in flight to prevent duplicate triggers; a rejected update check (e.g. another install task running) is never reported as "all up to date"

Mods

Mod files: upload .jar files into the server's mods/ folder (an existing file name asks for confirmation before overwriting); enable / disable by renaming foo.jar ↔ foo.jar.disabled; deleting permanently removes the file. Uploads, enable/disable and deletes only take effect after a server restart
Config files: browse every file under the server's config/ directory in a modal, open one and edit it, then save. The original encoding (UTF-8 / Latin-1), BOM and line endings are preserved. Binary files and files over 1 MiB are read-only, and .DS_Store files are filtered out. Clicking "Config" on a mod pre-fills the filter with that mod's id / name so its own files come up first instead of the whole directory

Server Settings

The top of the Server Settings page switches between two sub-tabs: Server settings and MCDR config.

Server settings: view and edit server.properties in the browser; the current file is shown next to the title in a monospace label. Settings render as a responsive card grid with localized labels, enumerated settings (difficulty, gamemode, …) appear as dropdowns, the list is filterable, and the toolbar shows the total and modified counts; saving rewrites only the keys you changed, comments and ordering are preserved, and modified cards are highlighted. Changes saved but not yet applied are marked "pending restart" with the original and new values (sensitive keys only show a "changed" hint, never the value); tracking survives plugin reloads and manual config edits, and clears automatically once the server restarts
MCDR config: on plugin load the panel inspects the running MCDR version's config.yml and renders visual cards grouped into Basic / Server / Plugin / Misc / Advanced / Debug, with dedicated controls for booleans, numbers and enums. Start command, RCON address, working directory, encoding, decoding and plugin directories use single-line inputs; list-typed fields (such as plugin directories or command arrays) are comma-separated in the input. Only keys that actually exist in the current MCDR version are shown, so the schema stays compatible across MCDR releases; unknown keys added by newer versions appear as generic inputs. The RCON password is never echoed and an empty submission keeps it unchanged. Saving automatically runs !!MCDR reload config so changes take effect immediately

Server settings

Server status

TPS, MSPT, swap, disk and system load at a glance
Line charts for CPU usage, memory usage and live network throughput, over 10m / 30m / 1h / 6h / 12h / 1d / 3d / 7d
Whole-host and Minecraft-process series are plotted separately. Samples are kept at 1-second resolution for the last hour and as 1-minute averages for the last 7 days

Server status

Other

Light / dark / follow-system themes, remembered across visits
UI language follows the browser automatically (Simplified / Traditional Chinese → Chinese, anything else → English), with a manual switcher on both pages that is remembered
Responsive layout that works on a phone browser

Installation

1. One-command install

!!MCDR plugin install minecraft_web_manager

2. Plugin management

See the official MCDReforged documentation: https://docs.mcdreforged.com/en/latest/command/mcdr.html#plugin-management

3. Grab the bootstrap password

On first load the plugin generates a one-time password and prints it to the MCDR log at WARNING level:

[Minecraft Web Manager] Minecraft Web Manager bootstrap password: xxxxxxxxxxxxxxxxxxxxxxxx

Save it right away — this is the only time it appears in plain text. Then open:

http://127.0.0.1:8088

The default username is admin; the password is the string above.

4. Forgot the password

Set both password.salt and password.hash to empty strings:

"password": { "salt": "", "hash": "" }

Save, then run !!MCDR reload plugin minecraft_web_manager — a fresh one-time password is printed to the MCDR log again.

Configuration

The config file lives at config/minecraft_web_manager/config.json inside MCDR's working directory. Reload the plugin for changes to take effect.

Key	Default	Description
`host`	`127.0.0.1`	Listen address. Local-only by default; set `0.0.0.0` to reach it from other machines
`port`	`8088`	Listen port
`username`	`admin`	Login username
`password.salt` / `password.hash`	generated	PBKDF2 salt and hash. The password itself is never stored
`token_secret`	generated	Signing key for login tokens. Clearing it invalidates every active session immediately
`token_ttl_seconds`	`2592000` (30 days)	Login session lifetime in seconds; sessions slide forward while actively used
`panel_title`	`MC Web Manager`	Panel brand title shown in the sidebar and browser tab (the login page title follows)
`bot_names`	`[]`	Player names manually flagged as fake players (lowercase); manual fallback on top of auto-detection
`not_bot_names`	`[]`	Reverse list (lowercase): forced to be treated as real players even if name rules or the offline UUID match; the per-row "unmark" button writes here
`bot_name_patterns`	`["(?i)^bot[_-]"]`	Regex list for bot-like names; by default only applies to players absent from usercache, so a real player named `bot_XXX` is not misclassified
`bot_name_patterns_apply_to_all`	`false`	Set to `true` to apply name rules to every player (for servers whose fake players do land in usercache); real players with matching names belong in `not_bot_names`

After login the browser receives an HttpOnly + SameSite=Strict session cookie (invisible to page scripts and never sent on cross-site requests), valid for 30 days by default. Active use keeps sliding the expiry forward, so normal usage does not require repeated logins. The "log out" button ends the session immediately; clearing token_secret also invalidates every session at once.

About RCON

Most features work without RCON, but these depend on it:

TPS / MSPT readings (via tick query)
Coordinates and dimension in the player roster
Seeing command reply text — only the RCON channel returns it
Recovering the online-player list after a plugin reload

Enabling it requires configuring both sides with a matching port and password:

Minecraft side: enable-rcon, rcon.port and rcon.password in server/server.properties
MCDR side: the rcon section of MCDR's config.yml

The three Minecraft-side settings can be edited right from the dashboard under Server Settings → Server settings; the server must be restarted afterwards. The MCDR side can be edited under Server Settings → MCDR config; saving automatically runs !!MCDR reload config.

Security notes

The dashboard has full control over your server — arbitrary commands, bans, config changes, plugin/mod management and file edits — so expose it carefully:

It listens on 127.0.0.1 by default. Keeping that and connecting through an SSH tunnel is the safest way to reach it remotely
If you must expose it publicly, put it behind a reverse proxy such as Nginx or Caddy with HTTPS enabled. The plugin does not provide TLS; over plain HTTP your password and token travel in the clear
The login endpoint has a simple failure throttle (10 attempts per 60 seconds per source) and the interactive API docs are disabled by default; the session cookie is HttpOnly with SameSite=Strict, so page scripts cannot read the token

A reverse proxy must forward WebSocket upgrades, otherwise the live console cannot connect:

location /ws/ {
    proxy_pass http://127.0.0.1:8088;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Sensitive settings such as rcon.password are shown blank and never sent to the browser; submitting an empty value leaves them unchanged
The MCDR config editor renders fields individually and never echoes the RCON password; submitting an empty password field keeps the current value

Known limitations

Resource history is kept in memory, so it resets to empty whenever MCDR restarts or the plugin is reloaded
World seed, name and difficulty are read from save files, which only update when the server writes them to disk — they can lag reality by minutes
Player IPs and UUIDs are parsed from server output, so unusual log formats may prevent capture. Players recovered after a plugin reload have no join time or IP
Only Fabric mods are identified (via fabric.mod.json); Forge / NeoForge mods are listed by filename only. Upload, enable/disable and delete operate on .jar files and do not depend on the loader
MCDR config is edited as visual fields and rewritten by ruamel.yaml on save; the field set is detected from the running MCDR version, and unknown keys from newer versions appear as generic inputs
Plugin check updates / updates require network access to the MCDR plugin catalogue, and only packed plugins (.mcdr / .pyz) can be updated; detailed output appears in the live console. The panel itself cannot be updated from the panel; run !!MCDR plugin install -U -y minecraft_web_manager and then !!MCDR reload plugin minecraft_web_manager in the MCDR console. The panel itself CAN be reloaded from the panel — it briefly goes offline and comes back automatically
Bot detection: classic Carpet bots are matched by their offline UUID. TIS/AMS/RMS-style extensions may give bots Mojang-resolved or random v4 UUIDs, which only name rules + usercache signals can catch. Name rules only apply to players with no usercache record; use not_bot_names or the per-row "unmark" action to force a real-player classification
Ping is unavailable on vanilla servers and therefore not shown
The dashboard UI currently supports Simplified Chinese and English

Feedback

Issues and suggestions are welcome at Issues.