📌Overview

Purpose: This plugin enables interoperability between Minecraft Java servers and client libraries written in various programming languages.

Overview: Minecraft Protobuf Queries (MCPQ) is a server plugin designed for Spigot or Paper Minecraft servers, facilitating modern communication between the server and client libraries using Protocol Buffers and gRPC. This allows for enhanced control and interaction through multiple programming languages.

Key Features:

• Interoperability: Supports client libraries in various languages through gRPC, promoting extensive compatibility and easier integration with external systems.

• Modern Communication Protocol: Utilizes Protocol Buffers and gRPC for efficient data serialization and communication, ensuring a modern approach to server-client interactions.

---

Minecraft Protobuf Queries (MCPQ) Server Plugin

This Minecraft Java server plugin allows other client libraries to control the server it is running on. These client libraries can be written in different programming languages, enabling interoperability between the Java plugin ecosystem and other languages. The plugin is designed to run on Spigot or Paper Minecraft servers.

It is inspired by RaspberryJuice and its client library MCPI, and provides a more modern communication approach that supports recent Minecraft versions.

MCPQ uses Protocol Buffers and the gRPC library and protocols to communicate with clients written in other programming languages and is itself written in Kotlin.

Versions

You can download the compiled and bundled jars in the release section of the repository and place them into your server's plugins folder:

server
│   paper/spigot-<version>.jar
└───plugins
    │   mcpq-<version>.jar
    │   ...

The plugin’s major version matches the protobuf protocol version, defining the communication features supported by the server. The minor version indicates patches and added functionality.

Compatibility depends on the Bukkit API version the plugin uses. Below is a compatibility summary:

Major (Protocol)	Minor (Plugin)	Minecraft Compatible	Release (Plugin Download)
1	0	1.18.2+	mcpq-1.0.jar

Example: The plugin mcpq-1.0.jar requires Minecraft version 1.18.2 or newer.

Typically, the plugin works with newer Minecraft versions with only minor functionality limitations. Backward compatibility with older client versions is maintained, but using newer clients with older plugin versions might only work across minor versions.

Recommendation: Download the newest plugin version supporting your Minecraft version (see table above).

Client Libraries

Client libraries enable communication with the server plugin. Thanks to gRPC, client implementations exist in many programming languages.

Currently available client implementation:

• Python: mcpq-python

If you create your own client for the protobuf interface, please notify the project to have it added to this list.

Configuration

The plugin generates/reads a config file at plugins/MCPQ/config.yml with these configurable options:

• host: localhost — Hostname or IP address from which connections are accepted. Default localhost allows only local connections; 0.0.0.0 allows connections from anywhere.
• port: 1789 — The port on which an MCPQ client connects.
• debug: false — Enables printing debug information, especially for gRPC.

Build Instructions

Before building, download the correct protobuf protocol version integrated as a git submodule at src/main/proto. Checkout the desired protocol version.

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/mcpq/mcpq-plugin

Or, if already cloned, update submodules:

git submodule update --init --recursive

Build the plugin using:

./gradlew shadowJar

Alternatively, use the shadowJar target in IntelliJ IDEA (Community Edition).

The final bundled jar with dependencies will be available at build/libs/mcpq-<version>-all.jar.

License

LGPLv3

The license permits use in any project type, including commercial or closed-source. However, modifications to the licensed software itself must be shared under the same license. For more details, see an in-depth explanation on open source licenses.