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
A simple tool to move and rename Nvidia Share recordings to a more sensible format.

A simple tool to move and rename Nvidia Share recordings to a more sensible format.

Jasper Rebane 8 Dec 23, 2022
A simple and easy to use Spam Bot made in Python!

This is a simple spam bot made in python. You can use to to spam anyone with anything on any platform.

7 Sep 08, 2022
Python USD rate in RUB parser

Python EUR and USD rate parser. Python USD and EUR rate in RUB parser. Parsing i

Andrew 2 Feb 17, 2022
ticktock is a minimalist library to view Python time performance of Python code.

ticktock is a minimalist library to view Python time performance of Python code.

Victor Benichoux 30 Sep 28, 2022
A primitive Python wrapper around the Gromacs tools.

README: GromacsWrapper A primitive Python wrapper around the Gromacs tools. The library is tested with GROMACS 4.6.5, 2018.x, 2019.x, 2020.x, and 2021

Becksteinlab 140 Dec 28, 2022
A morse code encoder and decoder utility.

morsedecode A morse code encoder and decoder utility. Installation Install it via pip: pip install morsedecode Alternatively, you can use pipx to run

Tushar Sadhwani 2 Dec 25, 2021
Fuzzy box is a quick program I wrote to fuzz a URL that is in the format https:// url 20characterstring.

What is this? Fuzzy box is a quick program I wrote to fuzz a URL that is in the format https://url/20characterstring.extension. I have redacted th

Graham Helton 1 Oct 19, 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
Python code to divide big numbers

divide-big-num Python code to divide big numbers

VuMinhNgoc 1 Oct 15, 2021
🔩 Like builtins, but boltons. 250+ constructs, recipes, and snippets which extend (and rely on nothing but) the Python standard library. Nothing like Michael Bolton.

Boltons boltons should be builtins. Boltons is a set of over 230 BSD-licensed, pure-Python utilities in the same spirit as — and yet conspicuously mis

Mahmoud Hashemi 6k Jan 04, 2023
These scripts look for non-printable unicode characters in all text files in a source tree

find-unicode-control These scripts look for non-printable unicode characters in all text files in a source tree. find_unicode_control.py should work w

Siddhesh Poyarekar 25 Aug 30, 2022
kawadi is a versatile tool that used as a form of weapon and is used to cut, shape and split wood.

kawadi kawadi (કવાડિ in Gujarati) (Axe in English) is a versatile tool that used as a form of weapon and is used to cut, shape and split wood. kawadi

Jay Vala 2 Jan 10, 2022
A work in progress box containing various Python utilities

python-wipbox A set of modern Python libraries under development to simplify the execution of reusable routines by different projects. Table of Conten

Deepnox 2 Jan 20, 2022
Make some improvements in the Pizza class and pizzashop file by refactoring.

Make some improvements in the Pizza class and pizzashop file by refactoring.

James Brucker 1 Oct 18, 2021
Pass arguments by reference—in Python!

byref Pass arguments by reference—in Python! byrefis a decorator that allows Python functions to declare reference parameters, with similar semantics

9 Feb 10, 2022
Check subdomains for Open S3 buckets

SuBuket v1.0 Check subdomains for Open S3 buckets Coded by kaiz3n Basically, this tool makes use of another tool (sublist3r) to fetch subdomains, and

kaiz3n 4 Dec 29, 2021
A python module to update the console without flashing.

A python module to update the console without flashing.

Matthias 112 Dec 19, 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
Here, I find the Fibonacci Series using python

Fibonacci-Series-using-python Here, I find the Fibonacci Series using python Requirements No Special Requirements Contribution I have strong belief on

Sachin Vinayak Dabhade 4 Sep 24, 2021
Let's renew the puzzle collection. We'll produce a collection of new puzzles out of the lichess game database.

Let's renew the puzzle collection. We'll produce a collection of new puzzles out of the lichess game database.

Thibault Duplessis 96 Jan 03, 2023