Skip to main content

Manage, configure, and create multiple Minecraft servers easily with a command-line interface.

Project description


A Minecraft Server Management Utility written in Python.

forthebadge made-with-python forthebadge for-sharks

GitHub license from Python Versions PyPI - Wheel


To use mcctl, your server setup should look something like this.

Starting from Version 0.4.0, a compiler (e.g. gcc), the Python3 Headers (python-dev or python3-devel) and systemd Headers (libsystemd-dev or systemd-devel) must be installed on your System before attempting Installation via pip.


The easiest way to install mcctl is via pip:

sudo pip install mcctl

Or even better: use pipx!

sudo -i
pip install --user pipx
echo "export PIPX_HOME=/usr/local/lib/pipx" >> ./bash_profile
echo "export PIPX_BIN_DIR=/usr/local/bin" >> ./bash_profile
# Reload environment variables
sudo -i 
pipx install mcctl

In some cases, the secure_path of sudo must be changed. If sudo mcctl returns "Command not found", add /usr/local/bin to your secure_path.

Getting started

As soon as mcctl is installed, you can create a new server:

sudo mcctl create myserver vanilla:latest -m 3G -p server-port=25566 "motd=My new fancy Minecraft Server!"
  • create: Sets up a new server and configures it accordingly.
  • Instance ID: gives the server a specific name (ID) which can be used in other commands.
  • Type ID: Specifies the Minecraft server type. Automatically downloads the "jar"-File if not cached.
  • Memory (-m): The amount of memory a server gets. Defaults are set via the systemd unit explained in Prerequisites.
  • Properties (-p): Options for the Values with spaces can be quoted as shown above.

The server is now created, but not running. For that, you can use the start command:

sudo mcctl start myserver -p
  • start: Starts a server.
  • Instance ID: The name of the server to start.
  • Persistent (-p): Sets up the server to be started after a reboot of the OS.

We can check if the server runs using the Command ls:

sudo mcctl ls -f myserver

Name           Server Version      Status      Persistent  
myserver       1.15.2              Active      True


In case you need to change the Unit Name or the Server User, it can be changed in /etc/mcctl.conf. The Config File can be created with the write-cfg-Subcommand.


  • systemd_service: The Service Prefix before "@INSTANCE_NAME". Default: 'mcserver'.
  • server_user: The User under which Servers can be managed and are run. Default: 'mcserver'.
  • env_file: The File in which Systemd Starting Options are specified. Default: 'jvm-env'.


  • editor The default Editor for interactive config editing. Default: 'vim'.
  • shell The default Shell for fully interactive configuration. Default: '/bin/bash'


mcctl is not well documented (yet). However, you should be able to answer a lot of your questions with the help parameter:

mcctl -h

Or for each Subcommand (e.g. create):

mcctl create -h


If you have suggestions, questions or issues, feel free to report them as an Issue here. Insights and Ideas of others are always welcome.


This Project is licensed under the GPLv3. Please see LICENSE for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcctl-0.4.3.tar.gz (43.9 kB view hashes)

Uploaded source

Built Distribution

mcctl-0.4.3-py3-none-any.whl (50.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page