A simple & intuitive Minecraft Server wrapper. Supports IRC, backups, a plugin system, and more.
Python JavaScript HTML CSS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.



Wrapper.py is an easy to use Minecraft server wrapper for adding extra functionality into the server without modifying the server jar file. It also comes with a relatively simple and straight-forward - yet powerful - plugin API that can be used to create Bukkit-like plugins with no server modding. The API works best when operated in proxy mode.

We also have a gitter channel: Join the chat at https://gitter.im/benbaptist/minecraft-wrapper

Wrapper.py Versions

NOTICE: Wrapper will Accept the minecraft server EULA on your behalf. 2


Wrapper.py supports the following features:

  • Plugin system for adding extra features to a vanilla server.
  • Permissions system with group support.
  • Proxy mode operation allows you to add extra bukkit-like functionality to plugins:
    • Real / command interface.
    • Built in hub worlds / multi-server support!
      • Use the built-in /hub functionality with world configurations set up in the wrapper config, or
      • Implement your own customized version with the plugin API by calling the player.connect() method.
    • Limit entity breeding / spawning with entity controls.
    • Monitor, Modify, and change:
      • player chat.
      • player block /digging/placement.
      • player inventory.
      • .. and More!
  • Automatic Backups
    • Automatically delete the oldest backups once you reach a specified number of backups
    • Specify which folders and files get backed up
  • IRC bridge
    • Controlling server from IRC
    • Achievements, deaths, and whatnot appear on IRC
    • Chat between Minecraft server and IRC channels
  • Scheduled reboots
  • Web remote for controlling the server and the wrapper through your web browser
  • Shell scripts that are called upon certain events (similar to plugin events, but quicker and easier)
  • Minecraft 1.7 and later support
  • Colorized console logging.


Python Versions

Python 3.5 + is suggested, However...


Wrapper.py requires the following packages:

  • Python packages: pip, requests, cryptography, bcrypt, setuptools, pkg_resources
  • Tar is required for backups.
  • More...

LINUX download and setup

Windows Download and setup

Start Up

You only need to download Wrapper.py. The '\wrapper' folder is the source code and is just the extracted version of Wrapper.py. Wrapper.py is a Python-executable archive folder containing the sourcecode.

To start Wrapper, open a console where the Wrapper.py or /wrapper sourcecode are located and type the following into the console to start:

python Wrapper.py|/wrapper [--passphrase 'passphrase'] The passphrase must be 8 or more characters in length!

Starting Wrapper.py for the first time...

Once wrapper has started:

  • Open the wrapper.properties.json file and tune the file to your remaining preferences.

  • Tune and setup your server and server.properties accordingly.

  • Restart wrapper.

    [15:28:08] [Server thread/INFO]: Starting minecraft server version 1.12.2
    [15:28:08] [Server thread/INFO]: Loading properties
    [15:28:16] [Server thread/INFO]: Preparing spawn area: 94%
    [15:28:17] [Server thread/INFO]: Done (7.956s)! For help, type "help" or "?"
    [15:28:17] [Wrapper.py/INFO]: Server started
    [15:28:17] [Wrapper.py/INFO]: Proxy listening on *:25566

Operating wrapper

  • Any console command beginning with a slash (/) will be interpreted firstly as a Wrapper.py command.

  • Type /help to see a list of Wrapper.py commands.

  • To completely shutdown the wrapper, type /halt.

  • To enter passwords into the wrapper.properties.config file, use the /password console command to enter the applicable password: /password Web web-password <new password>

Please read our Doc page for additional information and review the issues page before submitting bug reports.
If you run into any bugs, please do report them!

If you have questions, please use our Gitter page instead of creating an issue.


The references for the wrapper plugin API are here: Wrapper.py Plugin API

New Permissions System

A file in the wrapper root directory "superOPs.txt" now augments the "Ops.json" file. Operators in the ops.json file can be assigned a higher (wrapper) OP level. The contents of the file are laid out just like server.properties (lines of <something>=<value>).

Sample superops.txt:


Higher op levels are required to run sensitive wrapper commands like /perms.


The modern event list is updated with each build: Wrapper events 3

Check the 'example-plugins' and 'stable-plugins' folders to see some example plugins. These are very useful for seeing how the API functions.

  • TEMPLATE.py and EXAMPLE.py are mostly just shells of a plugin to work off of. They contain useful tutorial comments.
  • zombie.py is a fun test plugin that leaves behind undead versions of people when killed by undead mobs.
  • speedboost.py gives everyone a speedboost when someone dies - similar to survival games.
  • poll.py allows players to vote for certain things on the server. It isn't very up-to-date at the moment, however.
  • Essentials is a plugin loosely based off of Essentials for Bukkit.
  • WorldEdit - is a plugin loosely based on the WorldEdit for Bukkit by sk89q
  • SmallBrother is a lightweight logging plugin based on the old Bukkit plugin, BigBrother
  • Open.py is a plugin that opens a window with nothing. This plugin was probably just a test plugin and may not work, but contains example code for accessing packets from the player api.


If you want to see more error messages and other useful messages while developing plugins or debugging wrapper, look for the logging.json file and make changes to the "console" section:

        "console": {
            "stream": "ext://sys.stdout",
            "formatter": "standard",
            "class": "logging.StreamHandler",
            "filters": [
            "level": "INFO" <-- Set to DEBUG for more detailed output

1 - The old stable branch "master", version 0.7.6, build 83 has now been archived in the "Original" branch. The original version only supports minecraft versions up to 1.8.

2 - Using wrapper means you also accept the EULA, which will be set to true in the eula.txt file in your server folder. Mojang EULA

3 - The original Event list (Wrapper version 0.7.6) - 0.7.6 Wrapper list of events