pz-nitrado-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pz-nitrado-mcp Increase zombie population to insane and lower loot to rare"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | What it does |
| List every service on the account — use it to find your |
| Audit trail: who restarted, who changed which file, and when |
| Saved config snapshots — the server's config history |
| A config file as it was when a snapshot was taken |
| What changed between a snapshot and the live config |
| Online/offline, address, slots, players connected, version |
| Discover the real config paths (the server name is host-assigned) |
| List or recursively glob a remote directory |
| Read any file; |
| The main |
| Sandbox settings, searchable, with the docs for each enum |
| Change sandbox settings in place, comments preserved |
| Current |
| Available logs newest-first: console plus PZ's rotated logs |
| Tail the last N lines of a log, with an optional filter |
| Overwrite a file (keeps a timestamped |
| Set individual |
| Add / remove / replace mods, updating both id lists together |
| Restart the server so changes take effect — also starts a stopped one |
| Stop the server |
Every write takes a timestamped backup next to the original first, so a bad edit
is always recoverable from the file server. The five most recent backups per
file are kept and older ones are pruned — set PZ_BACKUP_KEEP to change that,
or to 0 to disable backups entirely.
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 # editable install; add ".[dev]" for testsOr straight from GitHub into an existing environment:
pip install git+https://github.com/aolmosj/pz-nitrado-mcp.git3. 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_idUse 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"]
}
}
}The installed console script works too, if you prefer a single token:
"command": "/absolute/path/to/.venv/bin/pz-nitrado-mcp" with no args.
Don't reach for a
cwdfield. It is tempting to skip the install and pointcwdat the checkout instead — but Claude Code does not apply it, so the server starts somewhere else, fails withNo module named pz_nitrado_mcp, and the client reports only-32000: Connection closed.claude mcp listshows the underlying error.
Configuration reference
Each setting is resolved from the first source that has it:
Setting | 1. Env var | 2. | 3. Config dir |
Token (required) |
|
|
|
Default service id |
|
|
|
XDG_CONFIG_HOME is honoured if set.
Two behaviour switches, environment-only:
Variable | Default | Effect |
|
|
|
|
| Backups retained per file; older ones are pruned after each write. |
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 logsDebugLog-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.
Sandbox settings
SandboxVars.lua holds ~270 settings — zombie population and speed, loot
rarity, day length, XP rates, erosion. Most are numeric enums whose meaning is
documented in comments right above them, and pz_get_sandbox returns those
comments alongside the value:
pz_get_sandbox(search="insane")
Zombies = 4
Changing this also sets the "Population Multiplier". Default = Normal
1 = Insane 2 = Very High 3 = High 4 = Normal 5 = Low 6 = NoneSo "make the zombies insane" becomes pz_set_sandbox({"Zombies": 1}) without
anyone having to memorise the numbering. Nested settings use dotted names
(ZombieLore.Speed, MultiplierConfig.*).
Edits are line-surgical: only the lines you name change, and the file's 738
comments, ordering and numeric formatting survive untouched. Writing 2 into a
setting that reads 0.8 produces 2.0, not 2.
Unknown setting names are rejected, not appended. The game silently ignores settings it doesn't recognise, so a typo would otherwise look like it worked and do nothing; the error suggests the closest real names instead.
Configuration history
Nitrado snapshots the config most days, and keeps whatever you save by hand —
the panel's "Perfiles de Configuración". pz_diff_config_profile is the useful
end of it: point it at a snapshot and it reports only what differs from the
config running now.
pz_diff_config_profile("09.07.2026 - 22:21")
differences: 111
PVP: 'false' -> 'true'
NoFire: 'true' -> 'false'
Mods: 'Ashenwood;BBL;Blackwood;…(+6000 more chars)' -> 'CleanHotBar'⚠️ These snapshots contain passwords in plain text — the admin password in the settings block, and the server and RCON passwords inside the config file. Every profile tool redacts them by default;
include_secrets=trueturns that off deliberately. A profile is a full copy of your config, so treat its output as sensitive.
Long values are abbreviated so one enormous Mods line doesn't bury the rest
of a diff; pass full_values=true when you need the whole thing.
Event log vs game log
Two different things, easy to confuse:
nitrado_event_log— what people did to the service. Restarts, stops, file uploads and deletions, settings changes, game installs, each with the account name and a timestamp. This is the panel's "Registro de eventos".pz_tail_log— what the game did. Startup sequence, errors, chat, connections.
"Who restarted the server at 3am?" is the first; "why did it crash?" is the second.
Config writes made through this MCP server show up in the event log as
filebrowser uploads, so its own activity is auditable alongside everything
else. Filtering is done client-side because the endpoint ignores filter
parameters, and category matching is case-insensitive — the live log contains
both server and Server, and an exact match silently drops the latter (which
is where the error entries live).
A note on mods
PZ needs two identifiers per mod and they are not interchangeable:
workshopId— the numeric Steam Workshop id, what the server downloadsmodId— the string from the mod'smod.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_configsandpz_list_logsreport what it found.Config files only exist after first boot. PZ writes
servertest.iniand friends when the server first starts, sopz_locate_configswill 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.
pz_restartis also "start". The API has no start action, so a server stopped withpz_stopcomes back only viapz_restart. A restart takes about a minute (started → restarting → stopping → started), and the status lags a few seconds behind the request — a status ofstartedimmediately after calling restart doesn't mean it was ignored.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 -e ".[dev]" # pytest + pytest-asyncio
.venv/bin/python -m pytest tests/ -qThe 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
Available Tools
20 toolsnitrado_event_logNitrado event logA
The account's audit trail for this service — the panel's 'Registro de eventos'. Records who did what and when: restarts and stops, config file uploads and deletions, settings changes, game installs. Call this for 'who restarted the server', 'what changed recently', or to see whether an action actually went through. This is about actions taken on the service; for what the game itself did, use pz_tail_log.
Inputs: limit, category, contains, severity, +1 more. Returns: result
nitrado_list_servicesList Nitrado servicesA
List every service on the Nitrado account with its id, game, status and expiry. Call this when you don't yet know the service_id of the Project Zomboid server, or when the user asks what they have hosted.
Inputs: no named parameters. Returns: result
pz_diff_config_profileDiff a configuration profile against the live configA
Compare a saved snapshot's server .ini with the one running now, and report only what differs. This is the tool for 'what changed since Friday', 'what did I break', or checking whether an edit actually landed. Passwords are redacted unless you ask for them.
Inputs: profile (required), service_id, full_values, include_secrets. Returns: result
pz_get_config_profileRead a configuration profileA
Return a config file exactly as it was when the snapshot was taken. Use this to see what a setting used to be, or to recover a value that was changed or lost. Passwords are redacted unless you ask for them.
Inputs: profile (required), file, service_id, include_secrets. Returns: result
pz_get_modsGet installed modsA
Return the current Mods and WorkshopItems lists in load order. Call this before changing mods, so you can see what is already installed.
Inputs: service_id. Returns: result
pz_get_sandboxGet sandbox settingsA
Read the sandbox tuning (SandboxVars.lua): zombie population and speed, loot rarity, day length, XP rates, erosion and so on. Roughly 270 settings, so pass search to narrow it — 'zombie', 'loot', 'day' — which also returns the in-file documentation explaining what each numeric value means. Call this before pz_set_sandbox so you use real setting names and the right enum numbers.
Inputs: search, service_id. Returns: result
pz_get_settingsGet parsed server settingsA
Read the main .ini and return it as a parsed key/value object. Call this when the user asks about a specific setting (password, max players, PVP, public name) — easier than reading the raw file.
Inputs: service_id. Returns: result
pz_list_config_profilesList configuration profilesA
List the saved configuration snapshots — the panel's 'Perfiles de Configuración'. Nitrado writes one automatically most days, plus any you save by hand, so this is the server's config history. Returns names, ids and dates only; use pz_get_config_profile or pz_diff_config_profile to look inside one.
Inputs: service_id. Returns: result
pz_list_filesList remote filesA
List a directory on the gameserver, or search it recursively when a glob pattern is given (e.g. '*.lua'). Call this to explore the server filesystem — saves, logs, mods — beyond the known config files.
Inputs: directory (required), search, service_id. Returns: result
pz_list_logsList server logsA
List the server's log files newest-first: the live console log plus PZ's rotated logs (chat, user, admin, map, pvp, DebugLog-server...), each with its kind, size and start time. Call this when the user asks what logs exist, or before tailing one you're not sure is there.
Inputs: service_id. Returns: result
pz_locate_configsLocate PZ config filesA
Discover the absolute paths of this server's config files (.ini, _SandboxVars.lua, _spawnregions.lua). The server name is host-assigned, so call this before touching any config path instead of guessing filenames.
Inputs: refresh, service_id. Returns: result
pz_read_fileRead a remote fileA
Read a file from the gameserver as text. Call this when you need the raw contents — a full SandboxVars.lua, a log, a save file. file may be an absolute path or one of the shortcuts 'ini', 'sandbox', 'spawnregions'.
Inputs: file (required), service_id. Returns: result
pz_restartRestart the serverA
Restart the gameserver so config or mod changes take effect. Players are disconnected. Call this after any write, once the user confirms. This is also how you START a stopped server — the API has no separate start action. Takes roughly a minute; pz_server_status may still report 'started' for a few seconds afterwards, so don't read a stale status as the restart having failed.
Inputs: message, service_id. Returns: result
pz_server_statusProject Zomboid server statusA
Live status of the PZ gameserver: online/offline, address, slots, players currently connected, game version and memory. Call this when the user asks whether the server is up, who is playing, or for the connection address.
Inputs: service_id. Returns: result
pz_set_modsSet modsA
Update Mods and WorkshopItems together. Each entry needs BOTH ids: workshopId is what Steam downloads, modId is what the game loads, and they are different identifiers. Array order is load order, which matters in PZ. Call this for any add/remove/reorder of the server's mod list.
Inputs: mods (required), mode, service_id. Returns: result
pz_set_sandboxSet sandbox settingsA
Change sandbox settings in place, preserving the file's comments, ordering and every setting you don't touch. Use dotted names for nested ones ('ZombieLore.Speed'). Values are the raw game values — look them up with pz_get_sandbox first, since most are numeric enums where 1 is not 'on' but a specific option. Takes effect after a restart.
Inputs: settings (required), service_id. Returns: result
pz_set_settingsSet server settingsA
Update individual keys in the main .ini while preserving comments, ordering and every other option; missing keys are appended. Call this for any change to server settings such as PublicName, Password, MaxPlayers or PVP.
Inputs: settings (required), service_id. Returns: result
pz_stopStop the serverA
Stop the gameserver. Call this only when the user explicitly wants the server down — to apply config changes use pz_restart instead. It stays offline until someone calls pz_restart, which is the only way back up.
Inputs: message, service_id. Returns: result
pz_tail_logTail a server logA
Read the last N lines of a server log. This is the tool to use for 'what happened', 'why did it crash', 'who connected', or 'show me the chat'. Only the tail is fetched, so it stays fast on multi-megabyte logs.
Inputs: log, lines, contains, service_id. Returns: result
pz_write_fileWrite a remote fileA
Overwrite a file on the gameserver, keeping a timestamped .bak copy of the previous content. Use this for whole-file replacements such as a rewritten SandboxVars.lua; prefer pz_set_settings for individual .ini keys. Takes effect after a restart.
Inputs: file (required), content (required), service_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Every tool has a clearly distinct purpose: service listing, live status, config file discovery, file operations, settings parsing, mod management, log tailing, config profile snapshots, sandbox editing, and lifecycle control. Overlaps like pz_read_file vs pz_get_settings are explicitly disambiguated in descriptions.
Most tools follow a consistent verb_noun pattern with a pz_ prefix, but two account-level tools use a nitrado_ prefix, creating a minor deviation. The prefix distinction is intentional and logical, but the mixed prefixes prevent a perfect 5.
At 20 tools, the server is slightly above the typical 3-15 well-scoped range, but each tool serves a distinct purpose in managing both the Nitrado account and the Project Zomboid server. The breadth is justified by the dual scope (account-level and server-level), so it's only slightly heavy.
The tool surface covers the full lifecycle of a PZ server: discovery, status, configuration (raw, parsed, and sandbox), mods, logs, config history, and restart/stop. Missing features like a separate start tool are unnecessary because restart serves that role, and the ability to read/write any file fills gaps.
Related MCP Connectors
MCP server for generating rough-draft project plans from natural-language prompts.
A MCP server built for developers enabling Git based project management with project and personal…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Manage game servers, configurations, players, and groups through the GameServerApp MCP server.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server for managing and monitoring Tailscale networks through natural language. It enables users to list devices, check connection status, monitor for client updates, and retrieve detailed tailnet summaries.69 npm7MIT
- AlicenseBqualityDmaintenanceMCP server for managing Bazzite Linux hosts, enabling system administration, desktop control, and gaming tasks through natural language.243MIT
- AlicenseNot gradedqualityDmaintenanceA Dockerized MCP server that enables Discord integration, offering tools for role management, messaging, moderation, and server administration via natural language.1MIT
- AlicenseBqualityBmaintenanceMCP server for managing Coolify instances, enabling control of applications, databases, services, servers, and more via natural language.13637 npmMIT