A Minecraft server inter-process communication library.
Project description
mcipc
A Minecraft inter-process communication API implementing the RCON and Query protocols.
Requirements
mcipc
requires Python 3.8 or higher.
Usage
Query protocol
The Query
protcol is used to query a Minecraft server for server information.
The Minecraft query protocol has two query modes: basic stats and full stats.
Basic stats
To get basic stats from a Minecraft server, it must enable the Query
protocol.
You can enable the query protocol on a Minecraft server by setting enable-query = true
in the server's server.properties
file.
To specify a deviating port, you can set query.port = <port>
in the same file.
The following example assumes a server running on 127.0.0.1
and on the default query port 25565
:
from mcipc.query import Client
with Client('127.0.0.1', 25565) as client:
basic_stats = client.basic_stats
print(basic_stats)
The type of basic_stats
is a named tuple with the following properties:
type
: The packet type (Type
, protocol information).session_id
: The query's session ID (int
, protocol information).motd
: The server's message of the day (str
).game_type
: The game type (str
).map
: The current map (str
).num_players
: The amount of online players (int
).max_players
: The amount of maximally allowed players (int
).host_port
: The server's port (int
).host_ip
: The server's IP address or hostname (ipaddress.IPv4Address
oripaddress.IPv6Address
orstr
).
Full stats
For retrieving full stats of a server, the same premises apply.
from mcipc.query import Client
with Client('127.0.0.1', 25565) as client:
full_stats = client.full_stats
print(full_stats)
The type of full_stats
is a named tuple with the following properties:
type
: The packet type (Type
, protocol information).session_id
: The query's session ID (int
, protocol information).host_name
: The server's message of the day (str
, same as BasicStats.motd).game_type
: The game type (str
).game_id
: The game ID (str
).version
: The game version (str
).plugins
: The used plugins (dict
).map
: The current map (str
).num_players
: The amount of online players (int
).max_players
: The amount of maximally allowed players (int
).host_port
: The server's port (int
).host_ip
: The server's IP address or hostname (ipaddress.IPv4Address
oripaddress.IPv6Address
orstr
).players
: The names of online players (tuple
ofstr
).
RCON protocol
The RCON
protocol is used to remotely control a Minecraft server, i.e. execute
commands on a Minecraft server and receive the respective results.
To enable RCON
on a Minecraft server, you must set enable-rcon = true
in the
server's server.properties
file.
Furthermore, you need to specify a port for the RCON server by setting rcon.port = <port>
and a password by setting rcon.password = <password>
in the same file.
The following example assumes a server running on 127.0.0.1
and on the RCON port 5000
with password 'mysecretpassword'
:
from mcipc.rcon import Client
with Client('127.0.0.1', 5000) as client:
client.login('mysecretpassword') # Perform initial login.
seed = client.seed # Get the server's seed.
players = client.players # Get the server's players info.
mansion = client.locate('Mansion') # Get the next mansion's location.
print(seed)
print(players)
print(mansion)
The type of seed
is Seed
which is derived from int
and can be used just like the latter.
The type of players
is Players
, a named tuple:
online
: The amount of online players (int
).max
: The amount of maximally allowed players (int
).names
: The names of online players (tuple
ofstr
).
The type of mansion
is Location
which describes the x-y-z location of the next located object.
x
: x-coordinate (int
).y
: y-coordinate (int
orNone
).z
: z-coordinate (int
).
HINT: The y-component of a location may be None
, which represents the special Minectaft vector component '~'
.
Available client commands
For a full documentation of available client commands, please refer to
help(Client)
within an interactive python shell.
Handling connection timeouts.
Since version 1.2.1, you can specify an optional timeout=<sec>
parameter on both Query
and RCON
clients.
If a timeout is reached during a connection attempt, it will raise a socket.timeout
exception.
The following example will raise a connection timeout after 1.5 seconds:
try:
with Client('127.0.0.1', 5000, timeout=1.5) as client:
<do_stuff>
except socket.timeout as timeout:
<handle_connection_timeout>
Scripts
This library also ships a couple of scripts intended as a proof-of-concept.
queryclt
: AQuery
client.rconclt
: AnRCON
client.rconshell
: An interactiveRCON
shell.
queryclt
queryclt
is a Query client script to communicate with minecraft servers via the Query protocol using the shell.
To communicate with a server, run:
queryclt <server> <stats_type> [<args>...] [options]
The placeholder <server>
can either be a pre-defined server's name (see below) or server socket identified by <host>:<port>
.
rconclt
rconclt
is an RCON client script to communicate with minecraft servers via the RCON protocol using the shell.
To communicate with a server, run:
rconclt <server> <command> [<args>...] [options]
The placeholder <server>
can either be a pre-defined server's name (see below) or server socket identified by [<password>@]<host>:<port>
.
If no password was specified in either the pre-defined server entry or the server socket, the script will interactively ask for the server's password.
Configuration
queryclt
servers can be configured in /etc/mcipc.d/query.conf
.
rconclt
servers can be configured in /etc/mcipc.d/rcon.conf
.
The configuration file format is:
[<server_name>]
host = <hostname_or_ip_address>
port = <port>
passwd = <password>
The passwd
entry is optional for rcon.conf
and unnecessary for query.conf
.
License
Copyright (C) 2018-2020 Richard Neumann
mcipc is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
mcipc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with mcipc. If not, see http://www.gnu.org/licenses/.
Legal
Minecraft content and materials are trademarks and copyrights of Mojang and its licensors. All rights reserved. This program is free software and is not affiliated with Mojang.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.