MineHelp

A Discord bot focused on Minecraft utility commands.

It can:

• check Minecraft server status
• show Mojang services status
• fetch player head/skin/full-body renders
• paginate random public server listings

Features

• Dual command system:
  • Prefix commands (>command)
  • Slash commands (/command)
• Caching layer for repeated lookups (./cache/*.json)
• Rich Discord embeds with user attribution
• Button-based pagination for server list browsing

Tech Stack

• Python 3.13+
• discord.py
• httpx
• beautifulsoup4 (bs4)
• python-dotenv

Commands

Prefix Commands

Prefix is currently hardcoded as >.

Command	Usage	Description
sevstatus	>sevstatus hypixel.net	Show Minecraft server status details
mojangstatus	>mojangstatus	Show Mojang services health
head	>head Notch 256	Show player head render (pixel optional, default 256)
skin	>skin Notch	Show player skin texture
body	>body Notch 256	Show full-body player render (pixel optional, default 256)
servers	>servers 20	Scrape random server list from Craftlist and paginate
ping	>ping	Bot latency check
help	>help	Show available prefix commands

Slash Commands

Slash commands are synced on startup using await bot.tree.sync().

Command	Usage	Description
/sevstatus	/sevstatus serverip:hypixel.net	Show Minecraft server status details
/mojangstatus	/mojangstatus	Show Mojang services health
/head	/head username:Notch pixel:256	Show player head render
/skin	/skin username:Notch	Show player skin texture
/body	/body username:Notch pixel:256	Show full-body player render
/servers	/servers from_no_of_pages:20	Scrape random server list with button pagination
/help	/help	Show available slash commands

Data Sources

• Mojang services: https://www.mcstate.net/api/mojang-status
• Server status: https://api.mcsrvstat.us/3/{serverip}
• Server icon: https://api.mcstatus.io/v2/icon/{serverip}
• Player renders/skins: https://api.mcheads.org
• Random server listings: https://craftlist.org

Setup

1) Clone

git clone https://github.com/CoderRony955/Minehelp.git

cd MineHelp

2) Create and activate virtual environment

python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1

3) Install dependencies

Recommended:

pip install -r requirements.txt

Alternative with uv:

uv sync

4) Configure environment variables

Create/edit .env:

BOT_TOKEN=your_discord_bot_token_here

5) Run the bot

python main.py

Discord Bot Configuration

• Enable Message Content Intent in the Discord Developer Portal (required for prefix commands).
• Invite bot with permissions to:
  • read/send messages
  • embed links
  • attach files
  • use slash commands/app commands

Caching Behavior

The bot stores successful lookups in JSON files under ./cache/, including:

• server_status.json
• player_head.json
• player_skin.json
• player_body.json
• servers.json

You can safely clear cache files when needed; they will be recreated automatically.

Notes

• The repo currently uses both pyproject.toml and requirements.txt. The dependency specifiers in requirements.txt are not standard pip syntax (=>), so prefer pip install -e . or uv sync.
• Some emoji characters in source output may appear garbled in certain terminals due to encoding/display differences.

License

Apache License 2.0