mcping

README

mcping 🏓

A fast, zero-dependency CLI tool for pinging Minecraft servers — Java and Bedrock.
Built in Go, works everywhere, gives you everything you need to know about a server in one command.

---

Features

• Java & Bedrock — ping both editions out of the box
• SRV lookup — automatically resolves SRV records (show them with --dns)
• Colorful output — MOTD rendering with full RGB support, color-coded ping
• Detailed mode — version info, player samples, Forge mods, secure chat status, and more
• EULA block check — find out if Mojang has blocked the server
• Repeat pings — run multiple pings with configurable delay
• Shell completions — bash, zsh, fish, and powershell (included in deb/rpm packages)
• Single binary — no runtime dependencies, a few MB, runs anywhere

---

Usage

mcping [flags] <server>

mcping hypixel.net
mcping -d play.example.com
mcping -b play.example.com        # bedrock
mcping -r 5 --delay 2 hypixel.net # 5 pings, 2s apart
mcping -D hypixel.net             # show DNS info

---

Flags

Flag	Short	Default	Description
--bedrock	-b	false	Ping a Bedrock server instead of Java
--details	-d	false	Show all server information in detail
--dns	-D	false	Display DNS info (SRV/A records)
--port	-p	25565/19132	Server port (auto-detected by edition)
--repeat	-r	1	Number of pings to send (0 = infinite)
--delay		1	Delay between pings in seconds
--eula-block-check	-e	false	Check if the server is blocked by Mojang
--protocol-version		32767	Protocol version for the handshake
--no-color		false	Disable colored output

Note: --eula-block-check and --protocol-version are ignored for Bedrock servers.
If you specify --port and the address already contains a port (ip:port), mcping will error out.

---

Installation

Homebrew (Linux & macOS)

You can install mcping using the custom Homebrew tap:

brew tap BlueTree242/homebrew-mcping
brew install mcping

Linux (quick install)

You can install mcping using the following script which will detect the proper package manager on your system and install the package from GitHub Releases.

curl -sL https://raw.githubusercontent.com/BlueTree242/mcping/main/scripts/install.sh | bash

# Via wget
wget -qO- https://raw.githubusercontent.com/BlueTree242/mcping/main/scripts/install.sh | bash

Manual Download

To install manually, download the appropriate package for your system directly from GitHub Releases and install:

Linux (deb/rpm/apk/pkg.tar.zst)

Download the .deb, .rpm, .apk or .pkg.tar.zst from GitHub Releases and install:

# Debian/Ubuntu
sudo dpkg -i mcping-*.deb

# RHEL/Fedora
sudo rpm -i mcping-*.rpm

# Alpine
sudo apk add --allow-untrusted mcping-*.apk

# Arch Linux
sudo pacman -U mcping-*.pkg.tar.zst

Windows

Download the .zip from GitHub Releases, extract mcping.exe, and either:

• Run it directly from the folder
• Add the folder to your PATH so you can run mcping from anywhere in cmd/powershell

macOS

Download the .tar.gz from GitHub Releases and extract:

tar -xzf mcping_*_darwin_*.tar.gz
sudo mv mcping /usr/local/bin/

---

Supported Platforms

OS	Arch	Formats
Linux	amd64, arm64	.deb, .rpm, .apk, .pkg.tar.zst, .tar.gz
Windows	amd64, arm64	.zip
macOS	amd64 (Intel), arm64 (Apple Silicon)	.tar.gz

---

Building from Source

You'll need Go 1.24+ and GoReleaser.

git clone https://github.com/BlueTree242/mcping.git
cd mcping

# snapshot build (all platforms)
goreleaser release --snapshot --clean

# or just build for your current OS
go build -o build/mcping

Artifacts end up in dist/.

---

Shell Completions

The .deb and .rpm packages install completions automatically for bash, zsh, and fish.

To generate completions manually:

# bash
mcping completion bash > /etc/bash_completion.d/mcping

# zsh
mcping completion zsh > "${fpath[1]}/_mcping"

# fish
mcping completion fish > ~/.config/fish/completions/mcping.fish

# powershell
mcping completion powershell | Out-String | Invoke-Expression

---

TO-DOs

• Query protocol support for Java servers
• JSON output for scripting and automation
• Print favicon in terminal alongside details
• Add subcommand to export favicon to .png file

---

License

MIT