# MCProtocolLib and the Java side of the Minecraft wire protocol

> MCProtocolLib is a Java library for writing bots, clients and servers that speak to Minecraft. It ships as a Maven artifact from the Open Collaboration repository, and its release tags are versioned against the Minecraft releases they track.

**GeyserMC/MCProtocolLib** — A library for communication with a Minecraft client/server.

- Repository: https://github.com/GeyserMC/MCProtocolLib
- Stars: 908 · Forks: 221
- Language: Java
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/geysermc-mcprotocollib

## A Java library aimed at custom bots, clients and servers

MCProtocolLib exists for a narrow and specific job: letting a Java program speak the Minecraft protocol directly rather than through a running game. The README describes it as a library for communicating with Minecraft clients and servers, and says it lets developers build custom bots, clients, or servers with ease. That is the whole scope. It is not a game, it is not a server implementation, and it is not a mod loader.

The audience is therefore Java developers who need to interact with Minecraft at the packet level. That covers proxy and server tooling, testing harnesses, protocol translators, and anything that wants to open a connection and exchange data without the official server code in the loop. It also covers people who want to read and write the protocol data structures themselves, which is where the module layout in the repository root becomes relevant.

Two of the three recent releases are named directly after Minecraft versions, and the third is too. That naming tells you how the project tracks upstream: the library follows the game, and a new Minecraft release means a new library release. The repository is not archived, and the last push was on 2026-10-14, so the code is still moving. The release list, however, stops at 1.21.4-1 on 2025-01-18, which is a gap worth understanding before you plan around it.

## Two modules in the repository root, one of them NBT flavoured

The top level of the repository contains a small number of meaningful entries. There is a protocol/ directory, a text-serializer-nbt/ directory, an example/ directory, a buildSrc/ directory, the Gradle wrapper files gradlew and gradlew.bat, and the build scripts build.gradle.kts and settings.gradle.kts. There is also a lombok.config file and a jitpack.yml.

The Maven coordinates the README gives point at the protocol module specifically, with the artifactId set to protocol and the groupId set to org.geysermc.mcprotocollib. The presence of a separate text-serializer-nbt directory suggests that NBT handling, the binary tag format Minecraft uses for its data, is handled as its own piece rather than folded into the protocol artifact. The README does not document that module, how to depend on it, or what it exposes, so anyone planning to use it has to inspect the source rather than follow the written instructions.

The lombok.config file and the buildSrc/ directory are the two entries that most directly hint at the implementation style. Lombok is a compile-time annotation processor that generates boilerplate accessors, and buildSrc/ holds custom Gradle build logic that is compiled alongside the build itself. Neither is explained in the README. The takeaway for an engineer is that the build is not plain Gradle, and a tool that assumes a stock Gradle project will need a small amount of adjustment.

## The dependency comes from Open Collaboration, not Maven Central

Adding MCProtocolLib to a Java project takes two steps, and both are configuration rather than installation. The README says builds are published to the Open Collaboration repository, which means a plain dependency declaration without a matching repository entry will fail to resolve. For Maven, the repository block is:

```xml
<repositories>
    <repository>
        <id>opencollab</id>
        <url>https://repo.opencollab.dev/main/</url>
    </repository>
</repositories>
```

The dependency itself is declared separately:

```xml
<dependency>
    <groupId>org.geysermc.mcprotocollib</groupId>
    <artifactId>protocol</artifactId>
    <version>(version here)</version>
</dependency>
```

Note that the version is a placeholder in both snippets, and the README leaves it that way. You have to pick a version yourself from the release list, and the release names carry a suffix such as 1.21.4-1 rather than a plain semantic version. Gradle users get the same two steps in either DSL, for example:

```groovy
repositories {
    maven { 
        name 'opencollab'
        url 'https://repo.opencollab.dev/main/'
    }
}
```

and:

```groovy
dependencies {
    implementation 'org.geysermc.mcprotocollib:protocol:(version here)'
}
```

The Kotlin DSL form is provided as well, using a maven block with a name property. If you need a build rather than a tagged release, the README points to a different URL for snapshots, switching the repository path to the maven-snapshots one. That switch changes where your artifact comes from and nothing else, which matters for reproducible builds.

## Building the source with the Gradle wrapper

The project builds with Gradle, and the wrapper scripts are committed at the repository root, so a clone comes with its own Gradle version rather than depending on what is installed on your machine. The README gives a single command for the whole build:

```bash
./gradlew clean build
```

That command is run in the project root directory. It is a build from source, not an install, and it produces nothing you can use directly in another project; the consumable output is the artifact published to the Open Collaboration repository.

The example directory is part of the repository and carries its own build.gradle.kts next to its example/src/ tree, so the sample usage is compiled as part of the same Gradle build rather than sitting in a separate project. That is the one part of the codebase you can read to learn the API without fetching an artifact, and it is also the only documentation of usage the README offers, since the README simply links to that example folder.

The Javadocs are hosted as well, and the README gives a URL that ends in the latest build under the maven-snapshots path. Pointing your IDE at the Javadoc host is a reasonable way to browse the classes without downloading anything, though the version you read there is the snapshot line rather than the tagged release you will end up depending on.

## Version tags are named after Minecraft releases, and the newest one is old

The three most recent releases are 1.21.4-1 on 2025-01-18, 1.21.2-1 on 2024-12-12, and 1.21-1 on 2024-11-03. The version part is the Minecraft version, and the trailing number is the library's own revision for that Minecraft version. This is a useful convention, because it lets you map a library artifact directly to a game client build.

It also puts the burden on you. There is no long term support branch, no patch line for older game versions, and no compatibility table in the README. If the Minecraft build your users run is not the one in the tag you chose, nothing in the documentation tells you what breaks. The library tracks the protocol, and the protocol changes between Minecraft versions in ways that a client library has to absorb.

The gap between the newest release and the current date is the practical point here. The last push was on 2026-10-14, so commits continue to land on the default branch master, but the release list has not added a new tag since 2025-01-18. Commits without a release mean the default branch may contain work that is not in any published artifact. If you need a released artifact, you are choosing among tags that are at best several months old, and you should check which one matches the Minecraft version you intend to connect to before writing any code against it.

## What this library is not: a plugin API for an existing server

The most common way to get this project wrong is to treat it as a normal server plugin. Java developers who want to add behaviour to a Minecraft server usually reach for a plugin API that runs inside the server process, where the server handles the network layer and the plugin calls into it. MCProtocolLib is not that. It is a client side of the conversation: it is the thing that opens a connection and exchanges protocol data with a server, which is why it is useful for bots and custom clients and also why it is a poor fit for extending a stock server.

There is a second limit worth stating plainly. The README documents how to add the dependency, how to build the source, and where the Javadocs live, but it does not document a session lifecycle, a login sequence, or a packet catalogue in prose. It points to the example folder for sample usage. That means the learning curve is carried by the example code and the Javadocs rather than by written documentation, and the amount of protocol knowledge you need to import is up to you.

For a team that only needs to send a chat message or read player positions, this library asks for considerably more than the task requires. It earns its place when you need to control the protocol conversation itself, not when you need a small amount of data from a server that already runs.

## Support runs through Discord, and the licence is MIT

There is no issue tracker discussion, no support portal and no documentation site in the README. The stated support channel is the GeyserMC Discord server, specifically the channel named #mcprotocollib, which the README describes as the place for discussion and support for this project. That is a reasonable place to ask about protocol behaviour, but it means your questions depend on other people being present, and it does not give you a durable record the way a repository issue would.

The licence is MIT. The LICENSE.txt file sits at the repository root, and the README links to the MIT licence text. For an organisation embedding this library in a commercial tool or a service, MIT is a permissive choice with a short set of obligations, chiefly keeping the copyright notice and licence text in the distribution. That is a straightforward commercial position, and the README gives nothing beyond the standard text, so if your use involves redistribution in a specific form, read LICENSE.txt yourself rather than relying on a summary.

One last operational detail: the README also references the Open Collaboration Maven snapshots for javadoc browsing, which means some documentation paths only exist on the snapshot side of the repository. Nothing in the project is hosted on Maven Central, so if your build environment has restricted access to third party artifact hosts, resolve that before you plan the integration rather than after.

## Conclusion

Adopt MCProtocolLib if you are writing a Java program that has to talk to a Minecraft client or server at the packet level and you are willing to track a protocol library that ships under a release tag rather than a continuous version. Do not adopt it for a Java plugin meant to run inside a normal server, because that is a different product, and do not assume the version tag on the artifact matches the Minecraft build your users run. Before starting, check the release list against the Minecraft version you need, confirm that your build can reach repo.opencollab.dev, and read the example module, because the README points there rather than documenting a usage API.

## FAQ

### How do I add MCProtocolLib to a Maven or Gradle project?

Add the Open Collaboration repository with the id opencollab and the url https://repo.opencollab.dev/main/, then depend on org.geysermc.mcprotocollib:protocol with a version you choose. The README leaves the version as a placeholder, so take it from the release list.

### Where can I find sample code for MCProtocolLib?

The README points to the example folder in the repository, at example/src/main/java/org/geysermc/mcprotocollib, which contains sample usage and is compiled as part of the project build.

### How do I build MCProtocolLib from source?

Run ./gradlew clean build in the project root directory, as the README states. The project uses Gradle to manage dependencies and ships the wrapper scripts gradlew and gradlew.bat in the repository.

### Is MCProtocolLib published to Maven Central?

No. Builds are published to the Open Collaboration repository, and snapshot builds use a separate URL under the maven-snapshots path. Javadocs for the latest build are hosted there as well.

### Which Minecraft version does the latest MCProtocolLib release support?

The most recent release listed is 1.21.4-1, published on 2025-01-18. Release names follow the Minecraft version, so the artifact tag tells you which client build a given release was cut for.

### What licence does MCProtocolLib use?

MCProtocolLib is licensed under the MIT licence, with the licence text held in LICENSE.txt at the repository root. The README links to the MIT licence text on the Open Source Initiative site.

## Sources

- [GeyserMC/MCProtocolLib on GitHub](https://github.com/GeyserMC/MCProtocolLib)
- [Issues](https://github.com/GeyserMC/MCProtocolLib/issues)
- [License: MIT](https://github.com/GeyserMC/MCProtocolLib/blob/master/LICENSE)
- [README](https://github.com/GeyserMC/MCProtocolLib/blob/master/README.md)
- [Releases](https://github.com/GeyserMC/MCProtocolLib/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/geysermc-mcprotocollib