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
Report Bobcat Status to Google Sheets

bobcat-status-reporter Report Bobcat Status to Google Sheets Why? I recently relocated my miner from my root into the attic. Bobcat recommends operati

Jasmit Tarang 3 Sep 22, 2021
convert a dict-list object from / to a typed object(class instance with type annotation)

objtyping 带类型定义的对象转换器 由来 Python不是强类型语言,开发人员没有给数据定义类型的习惯。这样虽然灵活,但处理复杂业务逻辑的时候却不够方便——缺乏类型检查可能导致很难发现错误,在IDE里编码时也没

Song Hui 15 Dec 22, 2022
Import the module and create an object of the class LocalVariable.

LocalVariable Import the module and create an object of the class LocalVariable. Call the save method with the name and the value of a variable as arg

Sajedur Rahman Fiad 2 Dec 14, 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
A time table app to notify the user about their class timings

kivyTimeTable A time table app to notify the user about their class timings Features This project incorporates some features i wanted to see in a time

null 2 Dec 15, 2021
An extremely simple package with a single utillity class used for gracefully handling POSIX shutdown signals.

graceful-killer An extremely simple package with a single utillity class used for gracefully handling POSIX shutdown signals. Installation Use pip to

Sven Ćurković 1 Dec 9, 2021
tade is a discussion/forum/link aggregator application. It provides three interfaces: a regular web page, a mailing list bridge and an NNTP server

tade is a discussion/forum/link aggregator application. It provides three interfaces: a regular web page, a mailing list bridge and an NNTP server

Manos Pitsidianakis 23 Nov 4, 2022
one_click_kag_server is a program which tries to fully automate the creation of a King Arthur's Gold server.

one_click_kag_server is a program which tries to fully automate the creation of a King Arthur's Gold server.

Benjamin Gorman 4 Jan 5, 2022
Multipurpose Growtopia Server tools, can be used for newbie to learn things.

Information Multipurpose Growtopia Server tools, can be used for newbie to learn things. Requirements - Python 3.x - Operating System (Recommended : W

Morphias 2 Oct 29, 2021
NetConfParser is a tool that helps you analyze the rpcs coming and going from a netconf client to a server

NetConfParser is a tool that helps you analyze the rpcs coming and going from a netconf client to a server

Aero 1 Mar 31, 2022
✨ Voici un code en Python par moi, et en français qui permet d'exécuter du Javascript en Python.

JavaScript In Python ❗ Voici un code en Python par moi, et en français qui permet d'exécuter du Javascript en Python. ?? Une vidéo pour vous expliquer

MrGabin 4 Mar 28, 2022
Simple python module to get the information regarding battery in python.

Battery Stats A python3 module created for easily reading the current parameters of Battery in realtime. It reads battery stats from /sys/class/power_

Shreyas Ashtamkar 5 Oct 21, 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
Python @deprecat decorator to deprecate old python classes, functions or methods.

deprecat Decorator Python @deprecat decorator to deprecate old python classes, functions or methods. Installation pip install deprecat Usage To use th

null 12 Dec 12, 2022
A python package containing all the basic functions and classes for python. From simple addition to advanced file encryption.

A python package containing all the basic functions and classes for python. From simple addition to advanced file encryption.

PyBash 11 May 22, 2022
Find dependent python scripts of a python script in a project directory.

Find dependent python scripts of a python script in a project directory.

null 2 Dec 5, 2021
A functional standard library for Python.

Toolz A set of utility functions for iterators, functions, and dictionaries. See the PyToolz documentation at https://toolz.readthedocs.io LICENSE New

null 4.1k Dec 30, 2022
Python Classes Without Boilerplate

attrs is the Python package that will bring back the joy of writing classes by relieving you from the drudgery of implementing object protocols (aka d

The attrs Cabal 4.6k Jan 6, 2023
🔩 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 4, 2023