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
Aggregating gridded data (xarray) to polygons

A package to aggregate gridded data in xarray to polygons in geopandas using area-weighting from the relative area overlaps between pixels and polygons.

Kevin Schwarzwald 42 Nov 09, 2022
ecowater-softner is a Python library for collecting information from Ecowater water softeners.

Ecowater Softner ecowater-softner is a Python library for collecting information from Ecowater water softeners. Installation Use the package manager p

6 Dec 08, 2022
Python Random Number Genrator

This Genrates Random Numbers. This Random Number Generator was made using python. This software uses Time and Random extension. Download the EXE file and run it to get your answer.

Krish Sethi 2 Feb 03, 2022
aws ec2.py companion script to generate sshconfigs with auto bastion host discovery

ec2-bastion-sshconfig This script will interate over instances found by ec2.py and if those instances are not publically accessible it will search the

Steve Melo 1 Sep 11, 2022
Casefy (/keɪsfaɪ/) is a lightweight Python package to convert the casing of strings

Casefy (/keɪsfaɪ/) is a lightweight Python package to convert the casing of strings. It has no third-party dependencies and supports Unicode.

Diego Miguel Lozano 12 Jan 08, 2023
Python type-checker written in Rust

pravda Python type-checker written in Rust Features Fully typed with annotations and checked with mypy, PEP561 compatible Add yours! Installation pip

wemake.services 31 Oct 21, 2022
Dill_tils is a package that has my commonly used functions inside it for ease of use.

DilllonB07 Utilities Dill_tils is a package that has my commonly used functions inside it for ease of use. Installation Anyone can use this package by

Dillon Barnes 2 Dec 05, 2021
Python Yeelight YLKG07YL/YLKG08YL dimmer handler

With this class you can receive, decrypt and handle Yeelight YLKG07YL/YLKG08YL dimmer bluetooth notifications in your python code.

12 Dec 26, 2022
Bounding Boxes Python Utils

Bounding Boxes Python Utils

Vadim 4 May 01, 2022
Dependency injection lib for Python 3.8+

PyDI Dependency injection lib for python How to use To define the classes that should be injected and stored as bean use decorator @component @compone

Nikita Antropov 2 Nov 09, 2021
API for obtaining results from the Beery-Bukenica test of the visomotor integration development (VMI) 4th edition.

VMI API API for obtaining results from the Beery-Bukenica test of the visomotor integration development (VMI) 4th edition. Install docker-compose up -

Victor Vargas Sandoval 1 Oct 26, 2021
A string to hashtags module

A string to hashtags module

Fayas Noushad 4 Dec 01, 2021
Auto-generate /etc/hosts for HackTheBox machines

Auto-generate /etc/hosts for HackTheBox machines Save yourself some tedium on getting started on a new machine by having your /etc/hosts ready to go.

3 Feb 16, 2022
Random Number Generator

Application for generating a random number.

Michael J Bailey 1 Oct 12, 2021
extract gene TSS/TES site form gencode/ensembl/gencode database GTF file and export bed format file.

GetTsite python Package extract gene TSS/TES site form gencode/ensembl/gencode database GTF file and export bed format file. Install $ pip install Get

laojunjun 7 Nov 21, 2022
Genart - Generate random art to sell as nfts

Genart - Generate random art to sell as nfts Usage git clone

Will 13 Mar 17, 2022
A plugin to simplify creating multi-page Dash apps

Multi-Page Dash App Plugin A plugin to simplify creating multi-page Dash apps. This is a preview of functionality that will of Dash 2.1. Background Th

Plotly 19 Dec 09, 2022
Easy compression and extraction for any compression or archival format.

Tzar: Tar, Zip, Anything Really Easy compression and extraction for any compression or archival format. Usage/Examples tzar compress large-dir compres

DanielVZ 37 Nov 02, 2022
Tools to connect to and interact with the Mila cluster

milatools The milatools package provides the mila command, which is meant to help with connecting to and interacting with the Mila cluster. Install Re

Mila 32 Dec 01, 2022
Python script to launch burp scans automatically

SimpleAutoBurp Python script that takes a config.json file as config and uses Burp Suite Pro to scan a list of websites.

Adan Álvarez 26 Jul 18, 2022