minecraft-admin

---
name: minecraft-admin
description: >
  Operate, update, and troubleshoot a self-hosted Minecraft Java server (Paper, Spigot, Purpur;
  Fabric and Forge aware) from an AI agent. Use when an operator asks to restart a Minecraft server
  safely, see who is online, run RCON or console commands, install, update or remove plugins
  (Modrinth, Hangar), edit plugin or server.properties configs, back up the world, announce or run
  events for players, add a live web map (BlueMap, Dynmap) behind nginx and HTTPS, set up
  whitelist or auth, or diagnose lag (low TPS), crashes, and out-of-memory kills.
license: MIT
metadata:
  short-description: AI skill for Minecraft server administration
  project: minecraft-admin-skill
---

# Minecraft Admin

An operating guide for AI agents (Claude Code, Codex, and similar) that administer a
self-hosted Minecraft Java server over SSH. It is not a server, a plugin, or a panel: it tells the
agent which checks to run first, how to change things without losing player progress, and what
to ask the human before doing anything players will notice.

## Operating model

Players are real people in a live world. Work in this order and do not skip steps:

1. **Identify the setup.** Server software (Paper, Fabric, Forge...), Minecraft version, how it
   runs (systemd unit, screen, Docker), install directory, and whether RCON is enabled. Plugins
   and mods are not interchangeable: a Fabric mod does nothing on Paper. Confirm the software
   before picking anything to install. See [references/setup-discovery.md](references/setup-discovery.md).
2. **Read before you write.** Players online, TPS, memory, recent log lines, loaded plugins.
3. **Back up, then change.** Copy the file or folder you are about to touch.
4. **Ask before anything players will notice.** Restarts, stops, world edits, whitelist or ban
   changes, resource-pack changes. Restarting with players online is the most common mistake.
5. **Verify after.** Server active, plugin list as expected, no new errors in `latest.log`,
   `list` shows the player count you expect.
6. **Report plainly.** What changed, what was backed up where, how to roll back, and what is
   still pending (for example "plugin removed from disk but still loaded until next restart").

## Hard rules

- Never restart or stop the server while players are online without the operator's explicit yes
  in this conversation. Offer a warning countdown (see the restart protocol).
- Never paste or echo the RCON password, server passwords, API keys, or tokens in replies,
  commits, or generated files. Keep them in a mode-600 file and read them from there.
- Never expose RCON (25575) to the internet. Bind it to localhost or firewall it.
- Never delete: move removed plugins and replaced configs to a backups folder with a date suffix.
- Never run the server as root. A dedicated user owns the install directory.
- Do not commit server IPs, domains, player names, or credentials to a public repo.
- Do not run `op`, `ban`, `kick`, `whitelist`, `stop`, `setblock`, `fill`, `kill @e`, or world-wide
  commands unless the operator asked for exactly that.

## Routing

| Task | Read |
| --- | --- |
| Work out what is installed and how it is run | [references/setup-discovery.md](references/setup-discovery.md) |
| RCON setup, safe command patterns, live status | [references/rcon-and-console.md](references/rcon-and-console.md) |
| Restart or stop with players online | [references/restart-protocol.md](references/restart-protocol.md) |
| Install, update, remove plugins; pick plugin vs mod | [references/plugins.md](references/plugins.md) |
| Edit plugin or server configs safely | [references/configs.md](references/configs.md) |
| Backups and restores | [references/backups.md](references/backups.md) |
| Messages, titles, sounds, events for players | [references/player-events.md](references/player-events.md) |
| Live web map behind nginx and HTTPS | [references/web-map.md](references/web-map.md) |
| Lag, crashes, OOM, "server won't start" | [references/troubleshooting.md](references/troubleshooting.md) |

## Bundled scripts

All scripts are small, read-only unless stated, and need only Python 3 and a POSIX shell.

- `scripts/mc_rcon.py` - minimal RCON client. Reads the password from a file, never from argv.
- `scripts/mc_status.sh` - one-shot health summary: service state, players, plugins, recent errors.
- `scripts/mc_restart.sh` - restart with player check, countdown, `save-all flush`, and verification.
  Refuses to run with players online unless `--yes` is passed after the operator agreed.
- `scripts/mc_plugin_install.py` - download a plugin from Modrinth for your version and loader,
  verify its hash, back up the plugins folder, and install the jar. Does not restart.

Run them on the server (or through `ssh host 'python3 -' < script`). Every script prints what it
is about to do and exits non-zero on failure.

## Reporting format

End each task with: **what changed**, **backups made**, **verification result**, **rollback command**,
and **anything pending a restart or operator decision**.

• AGENTS.md 1 KB
• CITATION.cff 1 KB
• LICENSE 1 KB
• README.ar.md 5 KB
• README.de.md 4 KB
• README.es.md 4 KB
• README.fa.md 6 KB
• README.fr.md 5 KB
• README.id.md 4 KB
• README.it.md 4 KB
• README.ja.md 5 KB
• README.ko.md 5 KB
• README.md 6 KB
• README.pl.md 4 KB
• README.pt-BR.md 4 KB
• README.ru.md 6 KB
• README.tr.md 5 KB
• README.zh-CN.md 4 KB
• SKILL.md 5 KB
• llms.txt 2 KB
• metadata.json 1 KB