Skip to main content

​
Overview

Modrinth is a modern, open-source mod hosting platform for Minecraft. MCReleaser provides full integration with Modrinth’s API, allowing you to publish versions of your projects with complete metadata, including loaders, game versions, dependencies, and more. The platform automatically filters and validates Minecraft versions based on your specified version type (release, snapshot, etc.) and supports both the production and staging Modrinth environments.

​
Required Credentials

To publish to Modrinth, you need:
  1. Modrinth Token: An API token from your Modrinth account settings
  2. Project ID: Your project’s slug or ID (found in your project URL)
You can create a Modrinth API token at modrinth.com/settings/pats. Make sure to grant it the CREATE_VERSION and UPLOAD_VERSION scopes.

​
Configuration Options

​
MODRINTH_TOKEN
string
required
The Modrinth API token for authentication. Create one from your account settings.
-e MODRINTH_TOKEN="mrp_your_token_here"
​
MODRINTH_PROJECT
string
required
The project ID or slug. You can find this in your project’s URL: https://modrinth.com/mod/[project-slug]Example: bettereconomy
​
MODRINTH_LOADERS
string
required
Space-separated list of mod loaders that your artifact supports.Valid loaders include: bukkit, spigot, paper, purpur, sponge, fabric, forge, quilt, neoforge, velocity, bungeecord, waterfallExample:
-e MODRINTH_LOADERS="paper purpur"
​
MODRINTH_GAME_VERSIONS
string
required
Space-separated list of Minecraft versions that your artifact supports. Can use version ranges.MCReleaser will automatically fetch and validate versions from Mojang’s version manifest.Examples:
# Specific versions
-e MODRINTH_GAME_VERSIONS="1.20.1 1.20.2 1.20.4"

# Version range
-e MODRINTH_GAME_VERSIONS="1.20-1.20.4"
If not set, falls back to the common GAME_VERSIONS variable.
​
MODRINTH_GAME_VERSION_TYPE
string
default:"release"
Filter game versions by type. Valid values: release, snapshot, old_alpha, old_betaThis is used when resolving version ranges to determine which versions to include.
-e MODRINTH_GAME_VERSION_TYPE="release"
If not set, falls back to the common GAME_VERSION_TYPE variable.
​
MODRINTH_VERSION_TYPE
string
default:"release"
The type of this release. Valid values: release, beta, alphaThis affects how the version is displayed on Modrinth.
-e MODRINTH_VERSION_TYPE="beta"
​
MODRINTH_DEPENDENCIES
string
JSON array of project dependencies. Each dependency specifies a project ID or slug and the dependency type.Dependency types: required, optional, incompatible, embeddedExample:
-e MODRINTH_DEPENDENCIES='[
  {"project_id": "fabric-api", "dependency_type": "required"},
  {"project_id": "modmenu", "dependency_type": "optional"}
]'
​
MODRINTH_FEATURED
boolean
default:"true"
Whether to feature this version on your project page.
-e MODRINTH_FEATURED="true"
​
MODRINTH_ENDPOINT
string
default:"production"
The Modrinth API endpoint to use for uploads.Valid values:Use staging for testing without affecting your live project.

​
Implementation Details

The Modrinth platform implementation performs the following steps:
  1. Version Resolution: Fetches the Minecraft version manifest and filters versions based on your criteria
  2. Metadata Preparation: Constructs the version metadata JSON including:
    • Project ID and version information
    • Game versions and loaders
    • Dependencies
    • Featured status
  3. Multipart Upload: Uploads the version using a multipart POST request containing:
    • JSON metadata as the data field
    • All artifact files as binary parts
Modrinth supports multiple files per version. MCReleaser will upload all files in your bundle and automatically designate the primary file.

​
Complete Example

java \
  -Dname="BetterEconomy" \
  -Dversion="2.1.0" \
  -Ddescription="## What's New\n\n- Added vault support\n- Fixed balance commands\n- Improved performance" \
  -DmodrinthToken="mrp_your_token_here" \
  -DmodrinthProject="bettereconomy" \
  -DmodrinthLoaders="paper purpur" \
  -DmodrinthGameVersions="1.20.1 1.20.2 1.20.4" \
  -DmodrinthGameVersionType="release" \
  -DmodrinthVersionType="release" \
  -DmodrinthFeatured="true" \
  -jar mcreleaser.jar

​
Advanced: Dependencies Example

Here’s a complete example with dependencies for a Fabric mod:
Docker
docker run \
  -v $(pwd)/build/libs:/app/artifacts \
  -e NAME="My Fabric Mod" \
  -e VERSION="1.0.0" \
  -e DESCRIPTION="A cool new mod!" \
  -e MODRINTH_TOKEN="$MODRINTH_TOKEN" \
  -e MODRINTH_PROJECT="my-fabric-mod" \
  -e MODRINTH_LOADERS="fabric quilt" \
  -e MODRINTH_GAME_VERSIONS="1.20.4 1.20.5 1.20.6" \
  -e MODRINTH_DEPENDENCIES='[
    {"project_id": "fabric-api", "dependency_type": "required"},
    {"project_id": "cloth-config", "dependency_type": "optional"},
    {"project_id": "modmenu", "dependency_type": "optional"}
  ]' \
  ghcr.io/hsgamer/mcreleaser:master

​
Source Code Reference

The Modrinth platform implementation can be found in:
  • Platform logic: modrinth/src/main/java/me/hsgamer/mcreleaser/modrinth/ModrinthPlatform.java
  • Configuration keys: modrinth/src/main/java/me/hsgamer/mcreleaser/modrinth/ModrinthPropertyKey.java

​
Key Implementation Features

// Version filtering with type support
MinecraftVersionFetcher.fetchVersionIds(gameVersionFilters, gameVersionTypeFilter)

// Request structure
JsonObject request = new JsonObject();
request.addProperty("project_id", ModrinthPropertyKey.PROJECT.getValue());
request.addProperty("featured", ModrinthPropertyKey.FEATURED.asBoolean(true));
request.addProperty("version_type", ModrinthPropertyKey.VERSION_TYPE.getValue("release"));
request.add("loaders", gson.toJsonTree(loaders));
request.add("game_versions", gson.toJsonTree(gameVersions));

// Multipart upload with all files
for (File file : fileBundle.allFiles()) {
    builder.addBinaryBody(file.getName(), file);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us