Minecraft - Online Players Overlay Generator


MOPOG (pronounced M-OH-PAWG) automatically generates an image displaying the players that are currently on a Minecraft server.

The intended use of the image is as an overlay on a live-stream, and works beautifully with OBS Studio.


online_players2 (Small)

Quick Start

There are two ways to use MOPOG:

  1. Download a pre-built binary (fast, easy, and still configurable!)
  2. Download and run the Python source (a bit more work, but allows deep customization!)

1. Download a Pre-Built Binary

1. Download the latest build

2. Run mowpog.exe

A configuration file called Minecraft_Online_Players_Overlay_Settings.ini will be generated.

3. Configure MOPOG For Your Server

Open Minecraft_Online_Players_Overlay_Settings.ini and change minecraft_server_ip and minecraft_server_port to correspond to your server. See Configuration for more details.

4. Restart MOPOG and Use the Generated Image as You See Fit

By default, an image called online_players.png will be saved to the same directory that the program is run in. The output directory can be changed - see Configuration.

2. Download and Run the Source Code

Python and Git are required for this method. MOPOG was developed using Python 3.9.9.
  1. Clone this repository
git clone https://elsell/MinecraftOnlinePlayersOverlayGenerator && cd MinecraftOnlinePlayersOverlayGenerator
  1. Install Dependencies
python -m pip install –upgrade && python -m pip install -r requirements.txt
  1. Run the Script
python MinecraftOnlinePlayersOverlayGenerator.py

See Command Line Options for more details.
A configuration file called Minecraft_Online_Players_Overlay_Settings.ini will be generated.

  1. Configure MOPOG For Your Server
    Open Minecraft_Online_Players_Overlay_Settings.ini and change minecraft_server_ip and minecraft_server_port to correspond to your server. See Configuration for more details.


MOPOG uses a configuration file to give you control over how it runs.

By default, the configuration file is named Minecraft_Online_Players_Overlay_Settings.ini and is generated on the first run of MOPOG.

Below is a copy of the default configuration file, containing a complete list of all configurable parameters.

NOTE: Some parameters are marked as optional and are not required to be in your configuration file.
# Minecraft_Online_Players_Overlay_Settings.ini

# (required) The directory in which the output image will be saved.
image_output_dir = .

# (optional) The filename of the generated image. 
image_name = online_players.png

# (required) The IP address of the Minecraft server you wish to query.
minecraft_server_ip = mc.3411heavenmedia.com

# (optional) The port on which the Minecraft server listens. 
minecraft_server_port = 25565

# (optional) Whether a faint shadow/outline will be drawn behind the player names.
#            Useful when overlaying on a light background.
draw_shadow = True

# (optional) The space between each player head as it's drawn on the image.
vertical_padding = 12

# (optional) How often to refresh the player list. For larger servers (> 25 players),
#            it is recommended that this be >= 30 seconds.
refresh_every_seconds = 10

Command-Line Options

- --help

Show available command-line options.


$ python MinecraftOnlinePlayersOverlay.py --help

usage: MinecraftOnlinePlayersOverlay.py [-h] [-log LOGLEVEL] [--config CONFIG]

optional arguments:
  -h, --help            show this help message and exit
  -log LOGLEVEL, --loglevel LOGLEVEL
                        Provide logging level. Example --loglevel debug, default=info
  --config CONFIG       Path to config file. Example --config my_custom_config.ini,

- --config <configuration_file>

Default: Minecraft_Online_Players_Overlay_Settings.ini

Pass a pre-existing/custom-named configuration file to MOPOG. If the file does not exist, it will be created with default values.


python MinecraftOnlinePlayersOverlay.py --config my_config.ini

- --loglevel <log_level>, -log <log_level>

Change the verbosity of MOPOG's logging.

Default: info

Valid options can be found on the Python logging library's website.


python MinecraftOnlinePlayersOverlay.py --loglevel debug


I'm getting an error about no players being found!

First, check that the server isn't using a plugin to spoof the number of players. Some servers show that they have players when they do not, but MOPOG sees the truth.

If you are still getting an error, there may be an incompatibility with the version of the server that is being queried. Please Submit an Issue so that we can get to the bottom of it!

Can I make the list lay horizontally?

Unfortunately, MOPOG currently only supports a vertical list. However, if you have Python experience and would like to contribute, feel free to fork this repo and add that feature!

Do I need to enable query in my server.properties?

Nope! MOPOG uses the same status request that the Minecraft client uses, and does not require query to be enabled in server.properties.

Is there any reason that MOPOG might stop working?

Yes! It's important to recognize that MOPOG relies on MC Heads to retrieve images of player skins. Should this service stop working, MOPOG would also stop working.

It would be possible to directly use the Mojang API, but using MC Heads was easier to set up.

If this becomes a problem, MOPOG will have to switch to using the Mojang API directly.

Will I get rate-limited?

Most APIs limit the number of times that a user can request information in a time period, including Mojang.

However, MOPOG uses MC Heads who do not enforce any rate-limit! Therefore you are free to set the refresh interval as low as you feel comfortable.

NOTE: Even though you are theoretically unlimited, very quick refresh rates could potentially slow down the Minecraft server.
In addition, the query itself often takes more than 1 second, so it's best to stick to a refresh interval that is no less than 5 seconds.

Projects Used

MOPOG doesn't work alone! Here is a small, non-comprehensive list, of projects that it uses:

GitHub - elsell/MinecraftOnlinePlayersOverlayGenerator at pythonawesome.com
Generate transparent overlays showing players on a Minecraft server! - GitHub - elsell/MinecraftOnlinePlayersOverlayGenerator at pythonawesome.com