pz-nitrado-mcp

An MCP server for managing a Project Zomboid dedicated server hosted on Nitrado, so you can check status, tune sandbox settings and manage mods by talking to Claude instead of clicking through the web panel.

There is no official Nitrado MCP server; the only community one targets ARK. This one speaks PZ: it knows where servertest.ini and SandboxVars.lua actually live, edits the .ini without trashing your comments, and keeps Mods and WorkshopItems in sync.

Tools

Every write takes a timestamped backup next to the original first, so a bad edit is always recoverable from the file server.

Related MCP server: bazzite-mcp

Setup

1. Get a Nitrado API token

In the Nitrado panel: your account menu → Developer (or /developer) → Create token. Tick the service scope and nothing else — it covers gameserver status, the file server and restarts. In particular do not tick service_order, which allows ordering (and paying for) new services. The token is shown once; treat it like a password.

2. Install

git clone https://github.com/aolmosj/pz-nitrado-mcp.git
cd pz-nitrado-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

3. Store the token

Put it in the shared config directory, so every project and session picks it up and it never lives inside an editor config file:

mkdir -p ~/.config/nitrado && chmod 700 ~/.config/nitrado
printf '%s' 'your-token-here' > ~/.config/nitrado/token
chmod 600 ~/.config/nitrado/token

# optional: a default service id, so tools can omit it
printf '%s' '1234567' > ~/.config/nitrado/service_id

Use printf rather than echo to avoid a trailing newline — though the server strips whitespace anyway. It warns on stderr if the token file is readable by other users.

Don't know your service id? Leave it out and ask nitrado_list_services.

4. Register it with Claude Code

Add to .mcp.json in your project (or ~/.claude.json for all projects). No credentials here — they come from the config directory:

{
  "mcpServers": {
    "pz-nitrado": {
      "command": "/absolute/path/to/pz-nitrado-mcp/.venv/bin/python",
      "args": ["-m", "pz_nitrado_mcp"],
      "cwd": "/absolute/path/to/pz-nitrado-mcp"
    }
  }
}

Configuration reference

Each setting is resolved from the first source that has it:

XDG_CONFIG_HOME is honoured if set. PZ_ALLOW_WRITES=0 runs the server read-only — no writes, no restarts — which is a reasonable default for a shared or automated setup.

Usage

Once registered, just ask:

• "¿Está arriba el servidor? ¿Quién está jugando?"

• "Sube la población de zombis a insane y baja el loot a rare"

• "Añade Authentic Z y Brita's Weapon Pack, y reinicia"

• "¿Qué mods tengo instalados ahora mismo?"

Reading logs

PZ rotates its logs on every server start, naming them DD-MM-YY_HH-MM-SS_<kind>.txt under Zomboid/Logs/, alongside a live server-console.txt. You don't need to know the timestamps — pz_tail_log takes a kind and resolves it to the most recent file:

• console — the live server console (default; where crashes and mod load failures show up)

• chat, user, admin, pvp, map, item, cmd — PZ's per-category logs

• DebugLog-server — verbose server debug output

Only the tail is fetched, using Nitrado's seek endpoint with a negative byte offset, so tailing a multi-megabyte log stays cheap. The endpoint caps each request at 64 KiB, so large tails page backwards in chunks. The optional contains filter is applied to the fetched window — if you expect older matches, raise lines rather than assuming there are none.

A note on mods

PZ needs two identifiers per mod and they are not interchangeable:

• workshopId — the numeric Steam Workshop id, what the server downloads

• modId — the string from the mod's mod.info, what the game loads

pz_set_mods takes both and keeps Mods= and WorkshopItems= consistent. List order is load order, which matters when mods conflict.

Notes and limitations

• Paths are discovered, not assumed. On Nitrado the gameserver root holds the game install; the server's own state lives under profile/Zomboid (Server/, Logs/, Saves/, server-console.txt). Other hosts differ, so the server probes candidate locations and identifies the right one by its contents. pz_locate_configs and pz_list_logs report what it found.

• Config files only exist after first boot. PZ writes servertest.ini and friends when the server first starts, so pz_locate_configs will fail on a server that has never run. Start it once from the panel.

• Changes need a restart. Nothing is applied live; every write tool says so.

• Build 42 wants at least 8 GB of RAM. If the plan is smaller, you will feel it once several players are on.

Development

.venv/bin/pip install pytest
.venv/bin/python -m pytest tests/ -q

The tests cover the config-manipulation logic — .ini editing, mod list merging, path resolution — which is the part that can corrupt a live server, and they run without touching the network.

License

MIT