Grasscutter: running a private Genshin server with Java 17 and MongoDB

What Grasscutter actually replaces, and for whom

Grasscutter is a server software reimplementation for a certain anime game, written in Java and licensed AGPL-3.0. The client still runs on your machine; what changes is where it connects. Instead of the official backend, the client talks to a server you run yourself.

The README lists what currently works: logging in, combat, friends list, teleportation, the gacha system, spawning monsters via console, and inventory features such as receiving items or characters and upgrading them. Co-op is described as working partially. That list is the honest scope of the project. It is not a full emulation of every service the retail game offers, and it is not a mod loader or a client patch.

The audience is narrow and specific. You need a game client at version REL4.0.x, a machine that can run Java 17 and MongoDB, and the willingness to follow a setup guide that the README says will have no handholding beyond the latest release. The README states plainly that Grasscutter has not been actively maintained and, as of January 12th, 2025, only works up to version REL4.0.1, the introduction to Fontaine. The last push to the repository was on 2026-03-04, but the newest tagged release, v1.7.4, dates to 2023-12-01. Anyone evaluating this for a long-lived deployment should weigh that gap.

How the server is put together: Java, MongoDB, KCP and a resource bundle

The repository is a Gradle project. The build file is build.gradle, the wrapper scripts are gradlew and gradlew.bat, and the source lives under src/. A plugin-schema.json at the top level indicates a plugin system with a defined schema, so extensions are expected to be written against that structure rather than by editing core files.

Runtime data is not all in the repository. The Dockerfile shows the split clearly: one build stage compiles the jar with Gradle, a second stage clones a resources repository from GitLab, and the final container copies both the built grasscutter-*.jar and the resources directory into place. The resource repository and branch are passed as build arguments, DATA_REPOSITORY and DATA_BRANCH, with the branch defaulting to 4.0. That default is the same version constraint the README repeats: the server data and the game client have to line up.

The container exposes ports 80, 443, 8888 and 22102. The topics list on the repository includes kcp, which is the transport the game uses, and 22102 is the port that appears in that exposure list. Persistence is MongoDB, which the quick start guide names as a prerequisite. The keystore.p12 file at the repository root is copied into the final image, which is what the server uses for its TLS material.

So the data flow is: the game client connects over the network to the Java server, the server reads and writes player state in MongoDB, and static game resources come from the cloned resource directory rather than from the client install.

Installing Grasscutter: the automatic path and the manual build

The README offers two routes. The automatic one goes through Cultivation, a separate launcher project from the same organisation, and is Windows-centric: it tells you to use the .msi installer and run it as admin.

Before either route, the prerequisites are the same. You need Java 17, MongoDB Community Server, and a game client at REL4.0.x. The README links to a client repository and a cloud drive for obtaining 4.0.x if you do not already have it.

In Cultivation, after opening it as administrator, you press the download button in the upper right corner and choose Download All-in-One. Then you open the gear menu and set two paths: the game install path to where your game is located, and the Custom Java Path to C:\Program Files\Java\jdk-17\bin\java.exe. Leave the other settings on default, press the small button next to launch, then the launch button. The README says to log in with whatever username you want and any password. That last detail is the clearest sign of what this server is: authentication is a formality, not a security boundary.

To build from source instead, clone with submodules because the project depends on them:

git clone --recurse-submodules https://github.com/Grasscutters/Grasscutter.git
cd Grasscutter

On Linux you make the wrapper executable and build the jar:

chmod +x gradlew
./gradlew jar

On Windows the equivalent is `gradlew.bat` followed by `gradlew jar`. The README notes that handbook generation can fail on some systems and that you can append `-PskipHandbook=1` to the jar command to skip it. The output jar lands in the root of the project folder. There is also a Dockerfile, whose final image runs entrypoint.sh and exposes ports 80, 443, 8888 and 22102, for people who would rather not install Java and MongoDB on the host at all.

Version pinning is the failure mode you will hit first

The README puts this in bold and repeats it: you cannot mix and match game versions and server versions. Download the correct version of Grasscutter for your version of the game. The Dockerfile encodes the same rule through DATA_BRANCH=4.0. If your client is 4.1 or later, the documented support stops at REL4.0.1, and the README says beta or unofficial builds are not officially supported, though you can try your luck in Discord.

This is not a configuration detail you can tune away. Resource data, protocol handling and the client build move together, so an upgrade on one side without the other is the most likely way to end up with a server that starts and a client that cannot get past login.

The second limitation is co-op. The README marks it as partially working rather than complete, so anyone planning to run this for a group should treat multiplayer as unproven at the documented version.

Third, the maintenance picture is thin. The README states the project has not been actively maintained. The repository is not archived and the last push was on 2026-03-04, but the newest release, v1.7.4, is from 2023-12-01. A project in that state can still run fine on a pinned version; what it will not do is absorb upstream changes for you. If your requirement is a server that tracks the current game, this is the wrong tool, and the README effectively says so itself.

Grasscutter compared with writing your own server or using a launcher-only tool

The realistic alternative is to implement the server yourself against the same protocol. That path gives you control over exactly which messages you handle and lets you target a game version the community has not documented. The cost is that you reimplement login, combat, inventory, gacha and teleportation from scratch, which is precisely the list of features Grasscutter already ships. For most people the trade is not close: Grasscutter's value is that someone else already wrote the protocol handling and the resource loading, and the Dockerfile shows the resource side is a cloned bundle rather than something you generate.

A second alternative is to use a launcher such as Cultivation without Grasscutter. That does not work as a substitute, because Cultivation is the thing that downloads and starts the server in the automatic path described above; it is a front end, not a server. The distinction matters when reading setup guides, because instructions that only cover the launcher leave out MongoDB, Java 17 and the resource bundle entirely.

A third comparison is against running the retail game normally. Grasscutter's reason to exist is the parts the retail service does not let you do: console monster spawning, direct inventory manipulation, and a server you control. If you do not need those, the official client is less work and has no version pinning problem.

Licence, upgrade cost and what the repository does not document

Grasscutter is AGPL-3.0. The practical consequence for anyone modifying it and offering it over a network is that the licence's source-availability terms apply to the modified version; the repository also carries a CODE_OF_CONDUCT.md and a contributing guide that contributors are asked to read before submitting. This is a description of the licence identifier, not legal advice, and anyone building a service on top of it should read the licence text itself.

Upgrade cost is dominated by the version rule. Because the server, the resource branch and the client build move together, an upgrade is not a jar swap. The Dockerfile makes this visible: DATA_BRANCH is a build argument, so changing it changes which resources ship inside the image. A deployment that pins 4.0 will stay on 4.0 until the client on the other side changes too.

The README is silent on several things a new operator would want. It does not document rollback, backup or migration of the MongoDB data. It does not describe the plugin system beyond the presence of plugin-schema.json. It does not give a troubleshooting table; it directs you to the Discord support channel instead. It also does not explain what the handbook contains, only how to build it with `./gradlew generateHandbook` or, via NPM, `cd src/handbook` followed by `npm install` and `npm run build`. Treat those gaps as work you will do yourself rather than as features that exist but are undocumented.

Editorial conclusion

Adopt Grasscutter if you already have a REL4.0.x client and want a local server for logging in, combat, teleportation, gacha and inventory work, and you accept that the README itself describes the project as not actively maintained. Do not adopt it if you are on a newer game build, expect co-op to be complete, or need a supported product with a support contract; the README points to the Discord for troubleshooting instead. Before committing, verify three things: that your client is exactly REL4.0.x, that Java 17 and MongoDB Community Server are installed, and that the server jar you build or download matches that client version, because the README states server and game versions cannot be mixed.

Frequently asked questions

Official sources

1. Grasscutters/Grasscutter on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases