MCP HubMCP Hub
mcpq

mcpq-python

by: mcpq

Python library for communicating with and controlling Minecraft servers via MCPQ plugin

8created 16/08/2024
Visit
Python
Minecraft

đź“ŚOverview

Purpose: The MCPQ Python Client Library is designed to facilitate interaction with a Minecraft Java Server (e.g., Spigot or Paper) using Python, enabling modern communication through the MCPQ plugin.

Overview: This library provides a modernized approach to control Minecraft servers via Python, inspired by earlier versions like MCPI. It utilizes Protocol Buffers and gRPC for efficient communication with servers, ensuring compatibility with newer Minecraft versions.

Key Features:

  • Modern Communication: Utilizes Protocol Buffers and gRPC for streamlined interactions between the Python client and Minecraft server, enhancing performance and compatibility.

  • Pythonic Interface: Offers an intuitive interface for Python developers, including convenient functions for sending commands and manipulating the game world (e.g., setting blocks, posting messages).

  • Turtle Module Integration: Comes with an integrated Turtle module for easy navigation and automation within the Minecraft environment, helping users learn coding while having fun.

Minecraft Protobuf Queries (MCPQ) Python Client Library

This library is designed to control a Minecraft Java Server, such as Spigot or Paper, running the mcpq plugin with Python. It aims to provide a modern approach for communication between the server and client for newer versions of Minecraft.

Requirements

  • Python 3.10+ is required due to the use of new type annotations.

Usage

To install the library, run:

pip3 install mcpq

Here's a quick example of how to use it:

from mcpq import Minecraft, Vec3

mc = Minecraft()  # Connect to server on localhost
mc.postToChat("Hello Minecraft!")
pos = Vec3(0, 0, 0)  # Origin of world
block = mc.getBlock(pos)  # Get block at origin
mc.setBlock("obsidian", pos)  # Replace block with obsidian
mc.postToChat("Replaced", block, "with obsidian at", pos)

Using the Turtle Module

A good starting point is the turtle module:

from mcpq import Minecraft, Vec3
from mcpq.tools import Turtle

mc = Minecraft()  # Connect to server on localhost
t = Turtle(mc)  # Spawn turtle at player's position
t.speed(10)

for i in range(4):
    t.fd(10).right(90)

Documentation

Explore the full documentation for the library by visiting the docs. The latest version is available there. For older versions, use git checkout vX.Y.Z to switch to a desired release and run make show_docs to serve the docs folder locally.

Versions

To see which version of the plugin is compatible with which Minecraft version, refer to the Minecraft version table.

The library version follows the major.minor.patch format:

  • major: Protocol version/tag
  • minor: Plugin version/tag
  • patch: Incremented with library enhancements

Ensure that the first two numbers (major.minor) match the plugin’s version.

Build Instructions

The library is published on PyPI and can be installed using:

pip3 install mcpq

To install directly from GitHub, you can use:

pip install git+https://github.com/mcpq/mcpq-python.git@<tag/branch>

To build the library locally:

python -m build
pip install dist/mcpq-0.0.0.tar.gz

If you need to rebuild protobuf files, first clone the proto submodule and then use:

make proto

License

This library is licensed under LGPLv3. Modifications to the licensed software must be shared under the same license.

For more information on the license, refer to the LGPLv3 explanation.