A Python class for checking the status of an enabled Minecraft server

Overview

travis build status current version supported python versions

mcstatus

mcstatus provides an easy way to query Minecraft servers for any information they can expose. It provides three modes of access (query, status and ping), the differences of which are listed below in usage.

Usage

from mcstatus import MinecraftServer

# If you know the host and port, you may skip this and use MinecraftServer("example.org", 1234)
server = MinecraftServer.lookup("example.org:1234")

# 'status' is supported by all Minecraft servers that are version 1.7 or higher.
status = server.status()
print("The server has {0} players and replied in {1} ms".format(status.players.online, status.latency))

# 'ping' is supported by all Minecraft servers that are version 1.7 or higher.
# It is included in a 'status' call, but is exposed separate if you do not require the additional info.
latency = server.ping()
print("The server replied in {0} ms".format(latency))

# 'query' has to be enabled in a servers' server.properties file.
# It may give more information than a ping, such as a full player list or mod information.
query = server.query()
print("The server has the following players online: {0}".format(", ".join(query.players.names)))

Command Line Interface

$ mcstatus
Usage: mcstatus [OPTIONS] ADDRESS COMMAND [ARGS]...

  mcstatus provides an easy way to query Minecraft servers for any
  information they can expose. It provides three modes of access: query,
  status, and ping.

  Examples:

  $ mcstatus example.org ping
  21.120ms

  $ mcstatus example.org:1234 ping
  159.903ms

  $ mcstatus example.org status
  version: v1.8.8 (protocol 47)
  description: "A Minecraft Server"
  players: 1/20 ['Dinnerbone (61699b2e-d327-4a01-9f1e-0ea8c3f06bc6)']

  $ mcstatus example.org query
  host: 93.148.216.34:25565
  software: v1.8.8 vanilla
  plugins: []
  motd: "A Minecraft Server"
  players: 1/20 ['Dinnerbone (61699b2e-d327-4a01-9f1e-0ea8c3f06bc6)']

Options:
  -h, --help  Show this message and exit.

Commands:
  json    combination of several other commands with json formatting
  ping    prints server latency
  query   detailed server information
  status  basic server information

Installation

mcstatus is available on pypi, and can be installed trivially with:

python3 -m pip install mcstatus

Alternatively, just clone this repo!

License

mcstatus is licensed under Apache 2.0.

Comments
  • Raising errors on invalid ip requires rewrite of client logic

    Raising errors on invalid ip requires rewrite of client logic

    I have code, that parsed and ensured the ip is valid. And all this with object from MinecraftServer.lookup. So I need to rewrite almost all code which uses mcstatus objects, just because da4770a88125346a10cc530a95bedd04892877f7. Add switch, or something like this please.

    Also I can't do fast-fix just with except: MineServer.lookup("not-valid.com") because object with offline server != object with invalid ip.

    P.S. I don't ask remove this feature, it would be nice to give messages like Invalid IP, reason: Port must be lower than 36635.

    Not Enough Information 
    opened by PerchunPak 15
  • Bedrock?

    Bedrock?

    Does it support bedrock edition? I can't seem to connect due to time out

    Traceback (most recent call last):
      File "C:\Python39\lib\site-packages\discord\client.py", line 343, in _run_event
        await coro(*args, **kwargs)
      File "D:\arjay\Documents\Personal projects\Python\hybridpe_discord\main.py", line 13, in on_ready
        status = server.status()
      File "C:\Python39\lib\site-packages\mcstatus\server.py", line 97, in status
        connection = TCPSocketConnection((self.host, self.port))
      File "C:\Python39\lib\site-packages\mcstatus\protocol\connection.py", line 131, in __init__
        self.socket = socket.create_connection(addr, timeout=timeout)
    
    
    opened by rjworks 15
  • query() not working

    query() not working

    I can't get the query() to work. I have enable-query set to true. I am just running the example code on the front page.

    Traceback (most recent call last): File "C:/Users/User/Desktop/server_status.py", line 17, in <module> query = server.query() File "C:\Users\User\AppData\Local\Programs\Python\Python36\lib\site-packages\mcstatus\server.py", line 82, in query raise exception File "C:\Users\User\AppData\Local\Programs\Python\Python36\lib\site-packages\mcstatus\server.py", line 77, in query querier.handshake() File "C:\Users\User\AppData\Local\Programs\Python\Python36\lib\site-packages\mcstatus\querier.py", line 32, in handshake packet = self._read_packet() File "C:\Users\User\AppData\Local\Programs\Python\Python36\lib\site-packages\mcstatus\querier.py", line 25, in _read_packet packet.receive(self.connection.read(self.connection.remaining())) File "C:\Users\User\AppData\Local\Programs\Python\Python36\lib\site-packages\mcstatus\protocol\connection.py", line 175, in read result.extend(self.socket.recvfrom(self.remaining())[0]) socket.timeout: timed out

    Question 
    opened by EnderInvader 15
  • Can't get response from a server

    Can't get response from a server

    Server: mermine.ru:19132 It is a PE server, but does answer regular query requests: https://mcsrvstat.us/server/mermine.ru:19132 (with "Bedrock server?" checkbox off).

    It does work with MinecraftBedrockServer, but does not with MinecraftServer, which is a bug/problem. What's up with this one?

    PS 1: It's a very recent version (v1.17.0) which uses a new protocol version - 440.

    PS 2: bedrock and regular queries return different answers.

    Bug 
    opened by MeRuslan 13
  • Improve documentation shown during autocomplete in IDEs

    Improve documentation shown during autocomplete in IDEs

    the documentation i can find is insufficient for the included features within this library and so all i have to go on is the short example at this page

    Feature Help Wanted 
    opened by apokalyps1 13
  • server.query() Timed Out

    server.query() Timed Out

    server.ping() and server.status() normal working but server.query() timed out.

    Traceback (most recent call last):  
      File "test.py", line 8, in <module>  
        query = server.query()  
      File "/usr/local/lib/python3.6/site-packages/mcstatus/server.py", line 169, in query  
        raise exception_to_raise_after_giving_up  
      File "/usr/local/lib/python3.6/site-packages/mcstatus/server.py", line 164, in query  
        querier.handshake()  
      File "/usr/local/lib/python3.6/site-packages/mcstatus/querier.py", line 48, in handshake  
        packet = self._read_packet()  
      File "/usr/local/lib/python3.6/site-packages/mcstatus/querier.py", line 41, in _read_packet  
        packet.receive(self.connection.read(self.connection.remaining()))  
      File "/usr/local/lib/python3.6/site-packages/mcstatus/protocol/connection.py", line 240, in read  
        result.extend(self.socket.recvfrom(self.remaining())[0])  
    socket.timeout: timed out
    

    python3.6 os: centos 7

    Question 
    opened by Gu-f 10
  • Asyncio streams are not being closed

    Asyncio streams are not being closed

    Whenever an async function is called a connection gets opened, but this connection never gets closed. This causes exceptions to be raised

    ERROR:asyncio:Exception in callback _ProactorBasePipeTransport._call_connection_lost(None)
    handle: <Handle _ProactorBasePipeTransport._call_connection_lost(None)>
    Traceback (most recent call last):
      File "C:\Program Files\Python39\lib\asyncio\events.py", line 80, in _run
        self._context.run(self._callback, *self._args)
      File "C:\Program Files\Python39\lib\asyncio\proactor_events.py", line 162, in _call_connection_lost
        self._sock.shutdown(socket.SHUT_RDWR)
    OSError: [WinError 10038] An operation was attempted on something that is not a socket
    

    This can be fixed by simply calling connection.writer.close() right before the return.

    Not Enough Information 
    opened by thesadru 10
  • Time out on 1.8.8 server

    Time out on 1.8.8 server

    Hi,

    i'm trying to use mcstatus to query the player list of my minecraft server. Unfortunately, no matter what I try, it doesn't work:

    Python 2.7.9 (default, Apr  2 2015, 15:33:21) 
    [GCC 4.9.2] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import mcstatus
    >>> server = mcstatus.MinecraftServer.lookup(myserverurl)
    >>> server
    <mcstatus.server.MinecraftServer instance at 0x7f5000eaa560>
    >>> server.ping()
    69.326
    >>> q = server.query()
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/usr/local/lib/python2.7/dist-packages/mcstatus/server.py", line 82, in query
        raise exception
    socket.timeout: timed out
    

    Traceback:

    Traceback:
    File "/home/mathias/.local/lib/python3.4/site-packages/django/core/handlers/base.py" in get_response
      132.                     response = wrapped_callback(request, *callback_args, **callback_kwargs)
    File "/home/mathias/Projects/mclobby/mclobby/views.py" in query
      26.         query = server.query()
    File "/home/mathias/.local/lib/python3.4/site-packages/mcstatus/server.py" in query
      82.             raise exception
    File "/home/mathias/.local/lib/python3.4/site-packages/mcstatus/server.py" in query
      77.                 querier.handshake()
    File "/home/mathias/.local/lib/python3.4/site-packages/mcstatus/querier.py" in handshake
      32.         packet = self._read_packet()
    File "/home/mathias/.local/lib/python3.4/site-packages/mcstatus/querier.py" in _read_packet
      25.         packet.receive(self.connection.read(self.connection.remaining()))
    File "/home/mathias/.local/lib/python3.4/site-packages/mcstatus/protocol/connection.py" in read
      172.             result.extend(self.socket.recvfrom(self.remaining())[0])
    

    The calls server.status() and server.ping() work just fine. Also on the example page http://dinnerbone.com/minecraft/tools/status/ I can query my server, presumably using the same code. Any idea what could be the problem?

    Question 
    opened by Bunkerbewohner 10
  • server query issue

    server query issue

    i am trying to make a python program where i get an email whenever certain people join the server, however when i try to query the server i get this error:

    Traceback (most recent call last): File "D:\Josh\Desktop\test1.py", line 5, in query = server.query() File "D:\Programs\python\lib\site-packages\mcstatus\server.py", line 82, in query raise exception File "D:\Programs\python\lib\site-packages\mcstatus\server.py", line 77, in query querier.handshake() File "D:\Programs\python\lib\site-packages\mcstatus\querier.py", line 32, in handshake packet = self._read_packet() File "D:\Programs\python\lib\site-packages\mcstatus\querier.py", line 25, in _read_packet packet.receive(self.connection.read(self.connection.remaining())) File "D:\Programs\python\lib\site-packages\mcstatus\protocol\connection.py", line 172, in read result.extend(self.socket.recvfrom(self.remaining())[0]) ConnectionResetError: [WinError 10054] An existing connection was forcibly closed by the remote host

    additional info: query is enabled in the server.properties running vanilla minecraft when using this site http://goo.gl/YRVYIQ i can see who is on the server just fine i get the error on both my raspberry pi and pc

    opened by wiihoffmann 10
  • How can I list plugins?

    How can I list plugins?

    Hello,

    is there any possible way to have only server plugins in the output? In issue #46 he gets plugins list and their versions. How can I replicate that?

    Cheers, Michal

    Question 
    opened by ElFrod0 9
  • Animated MOTDs result in errors.

    Animated MOTDs result in errors.

    I know it's not a proper part of the MOTD spec, but a lot of servers now are using "animated" MOTDs. As long as minecraft itself "supports" them, MCStatus should be able to at least get the first frame from an animated MOTD.

    opened by dmptrluke 9
  • Unable to use module in a python script

    Unable to use module in a python script

    I just installed mcstatus onto my machine after a few months of unuse, however when i attempt to use the modules i get different errors depending on where i run the file, from the terminal i get a "no module named mcstatus" and in VS code i get an "Import error" saying that there is a circular import somewhere although all i have is from mcstatus import MinecraftServer stranger yet vscode recognises the module and still gives prompts, im using v8.0.0 of the module with python 3.7, im running this in buster 10

    opened by KarsonTheFoxx 3
Releases(v9.0.0-dev5)
  • v9.0.0-dev5(Feb 6, 2022)

    What's Changed

    • Add timeout parameter propagation from lookup func by @Dominique57 in https://github.com/Dinnerbone/mcstatus/pull/176
    • Merge retry logic into a single decorator by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/186
    • Adding a Bedrock Example by @ChrisTracy in https://github.com/Dinnerbone/mcstatus/pull/191
    • Ensure the address is valid on server init by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/190
    • Cleanup the codebase by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/182
    • Link to PyPI repo from the badge by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/206
    • Switch type checker to pyright by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/199
    • Annotate alternative constructors with Self by @ItsDrike in https://github.com/Dinnerbone/mcstatus/pull/205
    • Strip HTML color codes from description parsing by @kevinkjt2000 in https://github.com/Dinnerbone/mcstatus/pull/196
    • fix motd unicode parse error. by @b23r0 in https://github.com/Dinnerbone/mcstatus/pull/192

    New Contributors

    • @Dominique57 made their first contribution in https://github.com/Dinnerbone/mcstatus/pull/176
    • @ChrisTracy made their first contribution in https://github.com/Dinnerbone/mcstatus/pull/191
    • @b23r0 made their first contribution in https://github.com/Dinnerbone/mcstatus/pull/192

    Full Changelog: https://github.com/Dinnerbone/mcstatus/compare/v8.0.0...v9.0.0-dev5

    Source code(tar.gz)
    Source code(zip)
  • v8.0.0(Jan 3, 2022)

    Support python 3.10 (27fbe2e) Lean more on poetry in the release script (aa43f01) Removed usage of six (c67dde8) Depend on tox and tox-poetry for development (f6b7a09) Cleanup tox.ini a bit (333858d) Fix broken test (30bc83f) Drop support for python 3.6 (#185)

    Source code(tar.gz)
    Source code(zip)
  • v7.0.0(Dec 9, 2021)

    This is mostly a development-specific release, but I bumped the major version because of the switch to poetry.

    • Close connection with destructor (#172)
    • Format strings (#167)
    • Switching to poetry (#165)
    • Removed outdated changelog (#170)
    • Fixing some development stuff on Windows (a31e808b1f35190c3875645e40d5bc31a6f3a950 d647b4eb25fe3e98c5ee856500901b6fa968f16c)
    Source code(tar.gz)
    Source code(zip)
  • v6.5.0(Aug 21, 2021)

  • v6.4.0(Jul 7, 2021)

  • v6.3.0(Jul 7, 2021)

  • v6.2.0(Jul 5, 2021)

  • v6.1.2(Jun 21, 2021)

    Fixed query protocol sending an extra zero #146 Fixed improper handling of varint by restricting to 32 bits-signed instead of 35-unsigned #141

    Source code(tar.gz)
    Source code(zip)
  • v6.1.0(Jun 15, 2021)

  • v6.0.0(Jun 1, 2021)

  • v5.2.0(May 1, 2021)

  • v5.1.4(Apr 11, 2021)

  • v5.1.3(Apr 11, 2021)

    async_ping fixed (#117)

    P.S.: I'm changing the release naming scheme from release-X.Y.Z to vX.Y.Z, because I plan to use git describe versioning at some point in the future to automatically publish releases from CI builds when new tags are published.

    Source code(tar.gz)
    Source code(zip)
  • release-5.1.2(Mar 30, 2021)

  • release-5.1.1(Jan 21, 2021)

  • release-5.1.0(Jan 19, 2021)

  • release-5.0.0(Jan 18, 2021)

  • release-4.1.0(Oct 30, 2020)

  • release-4.0.0(Aug 6, 2020)

    Rename retries to tries to better go along with the meaning of the word (#89) This is a breaking change for any code that was relying on passing named keyword arguments including this, hence the major bump in version.

    Source code(tar.gz)
    Source code(zip)
  • release-3.1.1(May 13, 2020)

  • release-3.1.0(Apr 9, 2020)

  • release-3.0.0(Apr 8, 2020)

  • release-2.3.0(Nov 16, 2019)

  • release-2.2.1(May 8, 2019)

Owner
Nathan Adams
Technical Director for Minecraft at @Mojang.
Nathan Adams
Conveniently measures the time of your loops, contexts and functions.

Conveniently measures the time of your loops, contexts and functions.

Maciej J Mikulski 79 Nov 15, 2022
JavaScript-style async programming for Python.

promisio JavaScript-style async programming for Python. Examples Create a promise-based async function using the promisify decorator. It works on both

Miguel Grinberg 191 Dec 30, 2022
cpp20.py is a Python script to compile C++20 code using modules.

cpp20.py is a Python script to compile C++20 code using modules. It browses the source files to determine their dependencies. Then, it compiles then in order using the correct flags.

Julien VERNAY 6 Aug 26, 2022
Python based utilities for interacting with digital multimeters that are built on the FS9721-LP3 chipset.

Python based utilities for interacting with digital multimeters that are built on the FS9721-LP3 chipset.

Fergus 1 Feb 02, 2022
Automatic generator of readmes for git repositories (Includes file' listing)

Readme Generator We are bored of write the same things once and once again. We trust in the comments made inside of our files, and we decided to autom

Natalia Vera Duran 6 Jul 20, 2021
Retrying is an Apache 2.0 licensed general-purpose retrying library, written in Python, to simplify the task of adding retry behavior to just about anything.

Retrying Retrying is an Apache 2.0 licensed general-purpose retrying library, written in Python, to simplify the task of adding retry behavior to just

Ray Holder 1.9k Dec 29, 2022
✨ Une calculatrice totalement faite en Python par moi, et en français.

Calculatrice ❗ Une calculatrice totalement faite en Python par moi, et en français. 🔮 Voici une calculatrice qui vous permet de faire vos additions,

MrGabin 3 Jun 06, 2021
Simple Python tool that generates a pseudo-random password with numbers, letters, and special characters in accordance with password policy best practices.

Simple Python tool that generates a pseudo-random password with numbers, letters, and special characters in accordance with password policy best practices.

Joe Helle 7 Mar 25, 2022
Two fast AUC calculation implementations for python

fastauc Two fast AUC calculation implementations for python: python-based is approximately 5X faster than the default sklearn.metrics.roc_auc_score()

Vsevolod Kompantsev 26 Dec 11, 2022
Python tool to check a web applications compliance with OWASP HTTP response headers best practices

Check Your Head A quick and easy way to check a web applications response headers!

Zak 6 Nov 09, 2021
The Black shade analyser and comparison tool.

diff-shades The Black shade analyser and comparison tool. AKA Richard's personal take at a better black-primer (by stealing ideas from mypy-primer) :p

Richard Si 10 Apr 29, 2022
A library for interacting with Path of Exile game and economy data, and a unique loot filter generation framework.

wraeblast A library for interfacing with Path of Exile game and economy data, and a set of item filters geared towards trade league players. Filter Ge

David Gidwani 29 Aug 28, 2022
Numbers-parser - Python module for parsing Apple Numbers .numbers files

numbers-parser numbers-parser is a Python module for parsing Apple Numbers .numbers files. It supports Numbers files generated by Numbers version 10.3

Jon Connell 154 Jan 05, 2023
A quick username checker to see if a username is available on a list of assorted websites.

A quick username checker to see if a username is available on a list of assorted websites.

Maddie 4 Jan 04, 2022
This program organizes automatically files in folders named as file's extension

Auto Sorting System by Sergiy Grimoldi - V.0.0.2 This program organizes automatically files in folders named as file's extension How to use the code T

Sergiy Grimoldi 1 Jan 07, 2022
VerSign: Easy Signature Verification in Python

VerSign: Easy Signature Verification in Python versign is a small Python package which can be used to perform verification of offline signatures. It a

Muhammad Saif Ullah Khan 3 Dec 01, 2022
Search, generate & deliver Msfvenom payloads in an quick and easy way

Goal Search, generate & deliver payloads in an quick and easy way Be as simple as possible BUT with all msfvenom payloads. Ever lost time searching th

2 Mar 03, 2022
A collection of custom scripts for working with Quake assets.

Custom Quake Tools A collection of custom scripts for working with Quake assets. Features Script to list all BSP files in a Quake mod

Jason Brownlee 3 Jul 05, 2022
✨ Un juste prix totalement fait en Python par moi, et en français.

Juste Prix ❗ Un juste prix totalement fait en Python par moi, et en français. 🔮 Avec l'utilisation du module "random", j'ai pu faire un choix aléatoi

MrGabin 3 Jun 06, 2021
Attempts to crack the compression puzzle.

The Compression Puzzle One lovely Friday we were faced with this nice yet intriguing programming puzzle. One shall write a program that compresses str

Oto Brglez 14 Dec 29, 2022