MCDReforged, and the robot that stares at the server console

How a Python process takes over a Minecraft server

MCDReforged, abbreviated MCDR, is a tool that provides the management ability of the Minecraft server using a custom plugin system, and it doesn't need to modify or mod the original Minecraft server at all.

The mechanism is described in four steps, and it is elegant enough that the project description ends with a summary of it: you can think of MCDR as a robot that stares at the server console and can quickly respond to server output and input related commands.

First, MCDR uses Popen to start the server as a sub-process. Second, it has the ability to control the standard input and standard output stream of the server. Third, since the console output of a Minecraft server has a stable format and contains a large amount of useful information, such as player chat messages, MCDR parses and analyses the server output, abstracts it into different events and dispatches them towards plugins for responding. Fourth, with the help of the Minecraft command system, MCDR sends Minecraft commands via the standard input stream to affect the actual server.

So the whole design rests on one observation, that a Minecraft server's console is a stable, documented-in-practice, line-oriented interface. Everything a plugin can do, it does by reading that stream and writing to it.

That is why the tool can work on vanilla, paper and bungeecord without cooperation from the server, and why it does not need to be recompiled when the server version changes. It is also why a plugin cannot do things the console does not expose, and understanding that boundary is more useful than any feature list.

Three advantages, and the one that constrains everything

The advantage list is short, and the first item is the one that decides the architecture.

It is running above the server. It doesn't need to modify the server at all, which keeps everything vanilla. The second is a hot-reloadable plugin system, so you don't need to shut down the server to update the plugins. The third is multi-platform and server compatibility, supporting vanilla, paper and bungeecord on Linux and Windows.

The first of those is the constraint behind everything else. Because MCDR is a parent process rather than a mod, the server binary is untouched and the installation is just a Python program and its plugins. There is no server jar to patch, no loader to install, and no risk that a server update breaks the integration. For an operator whose server is vanilla because of a policy or a hosting provider that only offers vanilla, that is the whole point.

Hot reloading is the second advantage and it is a real design constraint of its own. A plugin can be updated while the server is running, which means the plugin system has to isolate plugin state, and it means a plugin developer cannot assume that a module level variable survives a reload. It also means a badly behaved plugin can be replaced without downtime.

The range of things plugins do is given as examples rather than as a list of features: an in-game calculator, player highlighting, manipulating the scoreboard, managing structure files, and backup and load backup. Those are the kinds of task that are awkward in a plugin for the server itself and easy when you have a process sitting next to it with a console and a command line.

The plugin system, and the catalogue of plugins

Plugins are how MCDR is extended, and the project links a separate plugin collection repository for the catalogue.

The API model is implied by the architecture rather than described in detail in the project description. A plugin receives events, which are the parsed and abstracted forms of the server's console output, and it can send commands back. It can also read files from the server's directory, which is how the structure file management and the backup features work, since a structure file is a saved piece of the world and a backup is a saved copy of the world directory.

The catalogue being a separate repository is a good sign, because it means the plugin ecosystem is not locked to one author's schedule, and a plugin catalogue with many entries is evidence that the API is usable by people who did not design it.

The documentation is on its own site and is built with readthedocs, and the repository carries a docs directory as well, so the source of the documentation is in the same tree as the code.

For someone evaluating the project, the catalogue is the fastest way to judge whether the API covers their use case, because the examples in it are working code written by third parties rather than by the maintainer.

Packaging, the entry point, and a version number that lives in the code

The project is published on PyPI as mcdreforged, and the package manifest explains most of the installation story.

The console script is declared in the project scripts section.

mcdreforged

It points at mcdreforged.mcdr_entrypoint:entrypoint, so running the command starts the tool, and the tool then starts the server as its sub-process.

The metadata is mostly dynamic, which is worth noting. The version, the readme, the dependencies and the optional dependencies are all listed as dynamic, and the version is taken from an attribute, mcdreforged.constants.core_constant.VERSION_PYPI. The dependencies come from requirements.txt and the dev extras from requirements.dev.txt, so the requirements files are the single source of truth and the manifest follows them.

The package data is included, with include-package-data set to true and a MANIFEST.in in the repository root, which is how the plugins directory and the other resources that have to be present at runtime end up in the wheel.

The Python requirement is 3.9 or newer, and the classifiers list 3.9 through 3.14, so the project supports a wide range of interpreters, including the ones people actually have on the servers they run.

There is also a Docker image on Docker Hub, and the repository carries a docker directory, which is the practical way to run this on a small VPS without touching the host's Python.

The dependency list, and what each choice implies

The runtime requirements are short and specific, and several of them tell you what the tool does.

colorama>=0.4.4
colorlog>=6.4
packaging>=23.0
parse>=1.18.0
pathspec
prompt-toolkit~=3.0
psutil>=5.8.0
pydantic>=2.11
requests>=2.26
resolvelib
ruamel.yaml~=0.17
typing-extensions>=4.6.0
wcwidth

The parse library is the giveaway about the console parsing strategy, since it is a combinator library for building parsers out of small pieces, and MCDR is described as parsing and analysing the server's console output into events. prompt-toolkit is the library behind interactive command line applications, which is what a console you type commands into is. colorama and colorlog handle the colouring of that output, and wcwidth handles character widths for the display, which matters for a console that renders a table of player names.

pydantic is a validation library, and its presence tells you that configuration is parsed and validated rather than read loosely from files, which is the difference between a typo in a config being an error at startup and a mystery at runtime. ruamel.yaml is a YAML library that preserves formatting, which is the right choice for configuration files a server owner edits by hand.

psutil gives process information, which is how a tool that owns a server process keeps track of it. requests and resolvelib are for network access and for resolving dependency-like specifications, and packaging is for version handling.

The repository also has a mypy.ini, a tests directory, a requirements.dev.txt and a docs directory, so the typing and the tests are part of the project rather than an afterthought.

A rewrite of MCDaemon, and the licence that matters for plugins

The project description credits the idea to chino_desu and his MCDaemon 1.0, and the repository description says this is a rewritten version of MCDaemon, a Python tool to control your Minecraft server.

That lineage is worth noting because the rewrite is where the current architecture came from.

The licence is LGPL-3.0, and the manifest states it as LGPL-3.0-only with the licence file listed. For the tool itself that is unremarkable. For a plugin author it is the point that needs thinking about, because the LGPL is designed so that a library can be used by closed software as long as modifications to the library are published. A plugin that uses MCDR is a separate program, and the obligations depend on how the plugin is distributed and linked, which is a question for a licence lawyer rather than for a README.

The release history shows a project that is still moving. The recent versions are v2.16.0 from 2026-09-19, v2.15.7 from 2026-01-12 and v2.15.6 from 2026-01-02, and the last push was on 2026-10-15 with the repository not archived. The two 2026 releases are months apart, which is a slower cadence than the 2026-01 pair and suggests a maintainer working on a larger change rather than shipping constantly.

The README is available in English, Simplified Chinese and Traditional Chinese, and the author is reachable on Discord under Fallen_Breath.

Editorial conclusion

Adopt MCDReforged if you run a Minecraft server and want to add behaviour, a scoreboard, a chat calculator or a backup workflow without turning the server into a modded build, because the tool works above the server and leaves it vanilla. Do not adopt it if your plugin needs privileged access to the server internals, because the only channel it has is the console stream and the standard input. Before you build a plugin on it, read the documentation site, keep the LGPL-3.0 terms in mind if you intend to distribute a plugin, and test on a copy of the server first, since a plugin runs in the same process that owns the server.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. MCDReforged/MCDReforged on GitHub
3. Project website
4. README
5. Releases