minecraft-server-dl-cli

A simple CLI tool for downloading the official Minecraft Java server.jar by version.

This tool reads Mojang's official version manifest, resolves the requested Minecraft Java version, downloads the matching server.jar, and verifies the downloaded file using SHA1 when available.

Languages

• English
• 繁體中文

Features

• Download official Minecraft Java server.jar by version
• Uses Mojang's official version manifest
• Automatically names files as server_<version>.jar
• Supports custom output paths
• Supports SHA1 and file size verification
• Can print the resolved download URL without downloading
• No runtime dependencies

Official Data Sources

This tool uses Mojang/Minecraft official endpoints:

• Minecraft Java version manifest
• Official Minecraft Java server download page

The resolved server.jar URL usually points to:

https://piston-data.mojang.com/v1/objects/<sha1>/server.jar

Requirements

• Node.js 18 or later
• npm, pnpm, or yarn

Installation

Install globally from npm:

npm install -g minecraft-server-dl-cli

Then run:

mc-server-dl 1.21.8

Or use it directly with npx:

npx minecraft-server-dl-cli 1.21.8

Usage

mc-server-dl <version> [options]

Example:

mc-server-dl 1.21.8

This downloads:

server_1.21.8.jar

Options

Option	Description
-o, --output <path>	Custom output path
--no-verify	Skip SHA1 and file size verification
--url-only	Print the resolved server.jar URL without downloading
-h, --help	Show help message

Examples

Download a specific Minecraft Java server version:

mc-server-dl 1.21.8

Download and save to a custom path:

mc-server-dl 1.21.8 -o ./servers/1.21.8/server.jar

Print the official download URL only:

mc-server-dl 1.21.8 --url-only

Skip verification:

mc-server-dl 1.21.8 --no-verify

Exit Codes

Code	Meaning
0	Success
1	Unexpected error
2	Invalid CLI arguments
3	Failed to fetch or parse metadata
4	Minecraft version not found
5	Version exists, but no official server.jar is available
6	Download failed
7	File size or SHA1 verification failed

How It Works

1. Fetches Mojang's version manifest.
2. Finds the requested Minecraft Java version.
3. Fetches that version's metadata JSON.
4. Reads downloads.server.url.
5. Downloads the official server.jar.
6. Verifies file size and SHA1 when metadata is available.

Disclaimer

This project is not affiliated with Mojang Studios or Microsoft.

Minecraft is a trademark of Mojang Synergies AB. This tool only resolves and downloads files from official Mojang/Minecraft endpoints.

License

MIT