mcwrench, configure and tune any Minecraft server

Your AI Minecraft server administrator.

v1.2.0 · MIT · open source mcwrench Configure and tune any Minecraft server

Your AI assistant becomes an expert Minecraft server administrator. It audits configs, kills lag, wires proxies and permissions, picks plugin stacks, bootstraps servers, and learns any plugin's docs on demand. Any server type, any plugin, any panel.

Install it Read the docs Star on GitHub
Claude Code Claude.ai OpenAI Codex Google Antigravity Gemini CLI
13
specialist skills
5
AI runtimes
64
plugin docs
25
gamemode stacks

// why mcwrench

Server admin is config archaeology. This is the map.

YAML footguns, JVM flags, proxy handshakes, permission nodes, and a thousand plugins that each document themselves differently. mcwrench knows the patterns and looks up the rest.

Without it

  • ✕ Ten browser tabs of wikis and Discord pins
  • ✕ Copy-pasted flags that OOM your container
  • ✕ online-mode and forwarding mismatches that break joins
  • ✕ AI that invents config keys that do not exist

With mcwrench

  • ✓ One assistant that routes to the right specialist
  • ✓ Flags and limits tuned to your version and host
  • ✓ Cross-file checks that catch the real footguns
  • ✓ Real keys only, fetched from the plugin's own docs

// the toolbox

Thirteen skills, one router.

An always-on router engages on any server-admin topic and hands off to the right specialist. You just describe the problem.

🧭 always on

minecraft-server-router

The always-on hub. Engages on any server-admin topic and routes to the right specialist, so plain phrasing just works. You never call it directly.

🔍/mcwrench:audit

audit-config

Lints a config tree for footguns, performance and security, and flags plugin conflicts and missing deps.

🩺/mcwrench:diagnose

server-doctor

Reads a crash report or log and names the culprit, grades server health, and plans a 26.1 / Java 25 upgrade. Read-only.

📚/mcwrench:learn

learn-plugin-docs

Fetches and condenses ANY plugin's real docs, so answers cite sources. 64 plugins come pre-loaded for zero-network lookups.

⚡/mcwrench:perf

performance-tuning

TPS, MSPT, OOM, Spark profiling, Aikar's flags, and view and sim distance.

🔐/mcwrench:perms

permissions-helper

LuckPerms groups, tracks, contexts, meta, and node conventions.

🌐/mcwrench:proxy

proxy-network

Velocity and Bungee modern forwarding, and the forwarding.secret handshake.

🎮/mcwrench:gamemode

gamemode-stacks

Canonical plugin stacks for 25 archetypes, with config touchpoints and pitfalls.

🎨/mcwrench:brand

server-branding

Brand kit, MOTD, ranks, and store copy in the right format per plugin, with tone presets.

🚀/mcwrench:bootstrap

new-server-bootstrap

Fill v3 Paper download, Java 25, EULA, Aikar startup, and starter configs.

🪺/mcwrench:panel

pterodactyl-ops

Pterodactyl and Pelican: RCON, the Xmx and OOM footgun, backups, and the client API.

📜/mcwrench:skript

skript-author

Write and debug Skript with reload-safety and live syntax from the Skript Hub API.

🎲/mcwrench:create

gamemode-designer

The foundry. Invents and scores original gamemodes by combining archetypes with one twist, then turns the idea into a fun, buildable server plan, all locally. Take an idea to a server.

Plus /mcwrench:profile, which saves a server profile so answers stop re-asking your version, host, and stack.

// see it work

You ask in plain words. It answers with real keys.

A prioritised audit, the way mcwrench reports it. Critical first, with the exact file and key to change.

audit-config

you ▸ audit my paper config, it is behind velocity

CRIT spigot.yml bungeecord:true + paper-global velocity.enabled:true will not start. Pick one.

HIGH server.properties online-mode=true behind a proxy breaks UUIDs and skins. Set false.

HIGH paper-global.yml proxies.velocity.secret is empty. Paste the proxy forwarding.secret.

MED server.properties simulation-distance=10. 6 is plenty for your player count.

▸ 1 critical, 2 high, 1 medium. Fix the critical first; it blocks boot.

It never guesses

Unsure about a plugin? It runs learn-plugin-docs and reads the real docs before answering.

It is careful

Deleting worlds, exposing RCON, flipping online-mode: it warns and confirms first.

// learns from

Modrinth Hangar GitHub Oraxen SpigotMC Skript Hub PaperMC GitBook

// how it works

Trigger, route, learn, advise.

01

Trigger

Say "my SMP is laggy" or run /mcwrench:audit.

02

Route

It picks the right specialist and reads its playbook.

03

Learn

Unsure about a plugin? It fetches the real docs to _cache/ first.

04

Advise

Prioritised findings with exact file:key changes.

// install

Pick your runtime.

Skills are filesystem-based and do not sync between tools. Install in each surface you use.

Claude Code plugin + slash

Gemini CLI GEMINI.md + TOML

Codex / Antigravity .agents/skills

Claude.ai zip upload

Full guide: the docs.

// command reference

Nineteen slash commands.

The always-on router is the master; these nineteen commands are shortcuts to it. Shown for Claude Code (/mcwrench:*); the same intent works as plain language everywhere.

CommandDoes
minecraft-server-router masterAlways on. Engages on any topic and routes to the right specialist below
/mcwrench:learnFetch and condense any plugin's docs (64 pre-loaded)
/mcwrench:brandBrand kit, MOTD and ranks in the right format
/mcwrench:profileRemember the server so it stops re-asking
/mcwrench:createInvent a gamemode and plan a fun server
/mcwrench:auditLint a config tree, prioritised critical to low
/mcwrench:conflictsFlag plugin conflicts and missing deps
/mcwrench:diagnoseRead a crash report or log, name the cause
/mcwrench:healthGraded scorecard for a server folder
/mcwrench:upgradePlan a version/Java upgrade (26.1, Java 25)
/mcwrench:stackPre-load a gamemode's whole plugin-doc stack
/mcwrench:formatMiniMessage to/from legacy color
/mcwrench:perfFix lag, low TPS, or OOM (Spark-led)
/mcwrench:permsLuckPerms ranks, contexts, prefixes
/mcwrench:proxyVelocity and Bungee modern forwarding
/mcwrench:gamemodeCanonical plugin stack for an archetype
/mcwrench:bootstrapStand up a new Paper or Velocity server
/mcwrench:panelPterodactyl and Pelican RCON, OOM, backups
/mcwrench:skriptWrite and debug Skript with live syntax
/mcwrench:helpA capability map of every skill and command

Every command with examples lives in the docs.

// questions

Good to know.

Does it change my server by itself?+

No. It reads and advises, and gives you exact edits. Anything destructive (deleting worlds, exposing RCON) it warns about and confirms first.

Which AI tools does it work in?+

Claude Code, Claude.ai, OpenAI Codex, Google Antigravity, and Gemini CLI. One source of truth, installed per tool.

Does it support Folia or Bedrock?+

It targets Paper, Purpur, Folia, Vanilla, and Velocity. It defaults to recommending Paper, and engages on Java plus Bedrock via Geyser or Floodgate. Bedrock-only servers are out of scope.

Is it free and open source?+

Yes. MIT licensed. The docs-learner runs on stock Node 18+ with no install for the common paths.

Will it invent config keys?+

No. When it is not confident about a plugin, it fetches that plugin's real documentation first and answers from it, citing the source.

Stop guessing at YAML.

Drop mcwrench into your AI assistant and let it audit, tune, and run your server, with answers that cite real docs.

Get it on GitHub Download v1.2.0