pz-mcp-server

An MCP server for Project Zomboid mod development. It gives an AI assistant three things modders constantly need:

1. The Java API the game exposes to Lua — searchable, from the unofficial PZ Javadocs (Build 42).
2. The vanilla game files — the game's own Lua, its events, and its item/recipe scripts.
3. Mod project tooling — scaffold, validate, and lint a mod against the real API.

Everything runs locally; nothing is fetched at runtime.

Setup

Requires Node 18+.

git clone https://github.com/Svi-ra/pz-mcp-server.git
git clone --branch pages https://codeberg.org/albion/PZ-JavaDocs.git pz-javadocs-pages
cd pz-mcp-server && npm install && npm run build

Clone the Javadoc next to the server, so the layout is:

somewhere/
  pz-mcp-server/
  pz-javadocs-pages/      <- the `pages` branch, ~10k html files

That is where the server looks by default; otherwise set PZ_JAVADOC_DIR. Refresh the docs later with git pull inside that checkout.

Register with Claude Code

claude mcp add pz --scope user -- node /absolute/path/to/pz-mcp-server/dist/index.js

Or copy .mcp.json.example to .mcp.json in your modding folder and fill in the paths.

Environment

Variable	Default	Purpose
PZ_JAVADOC_DIR	../pz-javadocs-pages, then ./javadocs	Javadoc pages checkout
PZ_GAME_DIR	common Steam locations	Game install (the folder holding media/)
PZ_MODS_DIR	%USERPROFILE%/Zomboid/mods	Where mods live and get scaffolded
PZ_CACHE_DIR	./.cache	Derived class-hierarchy index

Run pz_status to see what got resolved. The four game-file tools return a clear error until PZ_GAME_DIR points at an install; every other tool works without the game.

Tools

Java API

Tool	What it does
pz_search_class	Fuzzy class search; also matches CamelCase initials (IGC → IsoGameCharacter)
pz_get_class	Signature, inheritance, fields, constructors, methods with javadoc. filter regex for big classes, include_inherited to pull in supertype methods
pz_search_member	Find a method/field across all 3,965 classes — "which class has getModData()?"
pz_list_package	Classes and sub-packages of a package
pz_get_hierarchy	Supertypes, subtypes, and interface implementors

Vanilla game files (needs PZ_GAME_DIR)

Tool	What it does
pz_search_lua	Regex search of media/lua, with optional path glob and context lines
pz_read_lua	Read a vanilla Lua file by line range (sandboxed to the install)
pz_list_events	Event names the game fires, with the files that declare or handle them
pz_search_script	Item/recipe/vehicle definitions from media/scripts, returned as whole blocks

Mod projects

Tool	What it does
pz_scaffold_mod	New mod skeleton: mod.info, client/server/shared Lua, a script file, a translation stub
pz_validate_mod	mod.info keys, poster, media/lua placement, script module wrappers, brace balance, Translate folders
pz_lint_lua	Flags :method() calls that exist on no Java class, engine globals that don't exist, and Events.X names the game never fires
pz_status	Which data sources resolved

Notes

• The scaffold defaults to the Build 42 layout (mods/<Mod>/42/mod.info + media/); pass layout: "b41" for the old flat layout, or version_dir: "common" for a build-agnostic mod.
• pz_lint_lua is heuristic. It only reports names that appear nowhere — not in the Java API, not in the mod, not in vanilla Lua — so dynamically built names can still produce false positives. It caught getBodyDammage(), getCellz() and a made-up event in testing while staying silent on correct code.
• The class hierarchy is parsed once from overview-tree.html and cached in .cache/.

Tests

npm run build
node test/smoke.mjs                    # every tool, over a real stdio session
node test/lint.mjs <mod-folder>        # validate + lint one mod
node test/gamefiles.mjs                # game-file tools (set PZ_GAME_DIR first)

Credits

The API data comes from albion's unofficial PZ Javadocs. This project only reads that checkout — it does not redistribute it.

Project Zomboid is a trademark of The Indie Stone. This is an unofficial, fan-made tool.

License

MIT — see LICENSE.