{"id":50116969,"url":"https://github.com/mcpq/mcpq-plugin","last_synced_at":"2026-05-23T15:33:53.863Z","repository":{"id":253592562,"uuid":"843372289","full_name":"mcpq/mcpq-plugin","owner":"mcpq","description":"Minecraft Java server plugin designed to allow other client libraries to control the server it is running on","archived":false,"fork":false,"pushed_at":"2026-03-14T00:02:21.000Z","size":111,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-14T12:04:07.519Z","etag":null,"topics":["java","kotlin","minecraft","minecraft-plugin","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcpq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-16T11:22:05.000Z","updated_at":"2026-03-14T00:02:03.000Z","dependencies_parsed_at":"2024-08-18T01:26:24.918Z","dependency_job_id":"5b026a1c-64d1-44c8-ac0f-90d52666f8af","html_url":"https://github.com/mcpq/mcpq-plugin","commit_stats":null,"previous_names":["mcpq/mcpq-plugin"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mcpq/mcpq-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpq%2Fmcpq-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpq%2Fmcpq-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpq%2Fmcpq-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpq%2Fmcpq-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcpq","download_url":"https://codeload.github.com/mcpq/mcpq-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpq%2Fmcpq-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33402165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","kotlin","minecraft","minecraft-plugin","protobuf"],"created_at":"2026-05-23T15:33:53.189Z","updated_at":"2026-05-23T15:33:53.858Z","avatar_url":"https://github.com/mcpq.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minecraft Protobuf Queries (MCPQ) Server Plugin\n\nThis Minecraft Java server plugin is designed to allow other *client libraries* to control the server it is running on. \nThese client libraries can be written in other programming languages thus allowing for interoperability between the Java plugin ecosystem and other languages.\nThe plugin is design to be run on [Paper](https://papermc.io/) Minecraft servers (alternatively [Spigot](https://www.spigotmc.org/) servers).\n\nThis plugin is heavily inspired by [RaspberryJuice](https://github.com/zhuowei/RaspberryJuice) (and its client library [MCPI](https://github.com/martinohanlon/mcpi)) and attempts a more modern approach for communication between server and client that also works for more modern versions of Minecraft.\n\nThis plugin uses [Protocol Buffers](https://github.com/mcpq/mcpq-proto) and the [gRPC](https://grpc.io/) library and protocols to communicate with clients written in other programming languages and is itself written in [Kotlin](https://kotlinlang.org/).\n\n## Usage\n\n* Download [Paper](https://papermc.io/downloads/paper) or another Minecraft server that implements its API (alternatively [Spigot](https://www.spigotmc.org/))\n* Download the compiled and bundled jar depending on the [table in versions](#versions) (but probably [latest](https://github.com/mcpq/mcpq-plugin/releases/latest))\n* Put the `mcpq-\u003cversion\u003e.jar` plugin in the server's `plugins` folder:\n  ```\n  server\n  │   paper-\u003cmcversion\u003e.jar\n  └───plugins\n      │   mcpq-\u003cversion\u003e.jar\n      │   ...\n  ```\n* Choose and install a supported [client library](#client-libraries), for example, [Python](https://github.com/mcpq/mcpq-python)\n* You're done!\n\n## Versions\n\n| Major (Protocol) | Minor (Plugin) |    Status    |     Paper     |    Spigot     | Minecraft Compatible |                       Release (Plugin Download)                       |\n|-----------------:|:---------------|:------------:|:-------------:|:-------------:|:--------------------:|:---------------------------------------------------------------------:|\n|                1 | 0              |    🟡️Old      |       ✅       |         ✅          |   1.18.2 - 1.21.4    | [mcpq-1.0.jar](https://github.com/mcpq/mcpq-plugin/releases/tag/v1.0) |\n|                2 | 0              |   🟢Spigot    | ✅\u003csup\u003e1\u003c/sup\u003e | ✅\u003csup\u003e1\u003c/sup\u003e |       1.20.1+        | [mcpq-2.0.jar](https://github.com/mcpq/mcpq-plugin/releases/tag/v2.0) |\n|                2 | 1              | ⚪️Deprecated |       ✅       |       ❌        |       1.20.1+        | [mcpq-2.1.jar](https://github.com/mcpq/mcpq-plugin/releases/tag/v2.1) |\n|                2 | 2              |    🟢Paper    |          ✅    |       ❌       |       1.20.1+        | [mcpq-2.2.jar](https://github.com/mcpq/mcpq-plugin/releases/tag/v2.2) |\n\n\u003e Version Notes: \u003cbr\u003e\n\u003e \u003csup\u003e1\u003c/sup\u003e: Limited output for blocking commands\n\n* The plugin's *major version* reflects the version number of the [protobuf protocol version](https://github.com/mcpq/mcpq-proto) and thus which types of communication is possible with the server.\n* The *minor version* is incremented with patches and additional functionality of this plugin.\n* The plugin is compatible with certain *Minecraft versions* depending on the *type and version of API the plugin uses*.\n  * E.g. the plugin `mcpq-2.0.jar` would require Minecraft Version 1.20.1 or newer for both Paper and Spigot (Spigot API)\n\n#### Paper and Spigot Compatibility\n\nTLDR; if you use Paper, then use a plugin that is build against Paper API (not Spigot compatible)\n\nOriginally the plugin was built against the *Spigot/Bukkit API*, which meant that [Spigot](https://www.spigotmc.org/) as well as all forks,\nlike [Paper](https://papermc.io/), were automatically supported.\nHowever, [Paper decided to hard fork Spigot](https://forums.papermc.io/threads/the-future-of-paper-hard-fork.1451/),\nwhich means that starting from Minecraft version 1.21.4 and onwards Paper will no longer be a fork of Spigot\nand thus the Paper API will slowly diverge from the Spigot/Bukkit API.\n\nFor us this means the following:\n* The [main branch](https://github.com/mcpq/mcpq-plugin/tree/main) will be built against the Paper API and *will no longer be compatible with Spigot*!\n* A separate [main-spigot branch](https://github.com/mcpq/mcpq-plugin/tree/main-spigot) will be maintained for Spigot compatibility.\n  * Provisionally, support for Spigot will remain in place for major releases and essential bug fixes.\n\nThis setup allows us to use the more powerful Paper API for plugin versions that are built against it,\nso if you are using Paper use a plugin that is build against that API instead!\n\n#### Protobuf Compatibility\n\nTLDR; download the newest version of the plugin that supports your Minecraft version and your server (see table above)\nand choose a client version that supports that version (or older)\n\nA plugin *should* be compatible with *older* client versions as backwards compatibility should be kept, which\nis enabled by the protobuf protocol. (Breaking changes of the protocol are recorded [here](https://github.com/mcpq/mcpq-proto?tab=readme-ov-file#version-changes))\n\n\u003e E.g., a *client* build against protocol v1 should also be able to communicate wtih a *plugin* built against protocol v2\n\nHowever, using *newer client* versions with older plugin versions will very likely *not* work and is not supported.\n\n\u003e E.g., a *client* build against protocol v2 *is not* compatible with a *plugin* built against protocol v1\n\n## Client Libraries\n\nA client library allows for communication with the server plugin.\nDue to its design [gRPC](https://grpc.io/) allows for implementations in a [large number of programming languages](https://grpc.io/docs/languages/).\n\nThe following official client implementations exist:\n\n* Python: [mcpq-python](https://github.com/mcpq/mcpq-python)\n\n\u003e If you implement your own client for the [protobuf](https://github.com/mcpq/mcpq-proto) interface, please let me know so that I can add a link to this list!\n\n## Configuration\n\nThe plugin comes with a config file that will be generated/read from `plugins/mcpq/config.yml` in which the following can be configured:\n\n* host: localhost - hostname or ip address from which connections to the plugin are accepted. The default `localhost` does only allow connections from the same device the server is running on, while `0.0.0.0` would allow connections from anywhere.\n* port: 1789 - the port on which a MCPQ client can connect to the plugin\n* debug: false - whether to print additional debug information especially for gRPC\n\n## Build Instructions\n\nBefore building make sure to download the correct version of the [protobuf protocol version](https://github.com/mcpq/mcpq-proto),\nwhich is integrated at `src/main/proto` as a git submodule, using one of the two methods below.\nYou can checkout the version of the protocol that you want to build for.\n\nWhen cloning the repository, either clone it with:\n\n```bash\n# clone the repository and all its submodules\ngit clone --recurse-submodules https://github.com/mcpq/mcpq-plugin\n```\n\nor, if you already cloned the repository:\n\n```bash\n# update and clone into the repository all submodules\ngit submodule update --init --recursive\n```\n\nTo build the plugin use `./gradlew build` or use the `build` target with the gradle plugin for *IntelliJ IDEA* (Community), which I also recommend for development.\n\nThe final plugin with all dependencies included will be a bundled `jar` at `build/libs/mcpq-\u003cversion\u003e.jar`.\n\n## License\n\n[LGPLv3](LICENSE)\n\n\u003e Note: The *intent* behind the chosen license, is to allow the licensed software to be *used* (as is) in any type of project, even commercial or closed-source ones.\n\u003e However, changes or modifications *to the licensed software itself* must be shared via the same license openly.\n\u003e Checkout [this blog](https://fossa.com/blog/open-source-software-licenses-101-lgpl-license/) for an in-depth explanation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcpq%2Fmcpq-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcpq%2Fmcpq-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcpq%2Fmcpq-plugin/lists"}