pz-ai-director
A Project Zomboid Build 42 Lua Mod + Python MCP Server bridge that turns any MCP-compatible AI assistant (Antigravity, Claude Desktop, Cursor) into a live AI Game Master & Military Radio Dispatcher (98.4 MHz) for solo or co-op campaigns.
Documentation
Project Zomboid AI Director (Build 42 MCP Bridge)

A Project Zomboid Build 42 Lua Mod + Python MCP Server bridge that turns any MCP-compatible AI assistant (Antigravity, Claude Desktop, Cursor) into a live AI Game Master & Military Radio Dispatcher (98.4 MHz) for solo or co-op campaigns.
Features
- Real DynamicRadio Channel (
98.4 MHz): RegistersExtraction Command [98.4 MHz]inside Project Zomboid's radio system (AIDirectorRadio.lua). - Two-Way Player Comms: Players can transmit via right-click context menu (
Extraction Radio [98.4 MHz]), tuned handheld/vehicle radios, or multiplayer chat (@message/!ai message). - Live Telemetry (
get_game_state): Coordinates, nearest Kentucky landmark, health, infection/bites/bleeding, hunger/fatigue/panic, vehicle fuel & condition, weather, and unread player radio messages. - 16 Real-Time Director Tools:
send_radio_transmission— Broadcast voice/HUD radio lines in any language (radio_and_hudorstrict_radio).give_starter_radios— Equip players with tuned98.4 MHzmilitary walkie-talkies.spawn_supply_drop— Drop crates with smoke flares, ground loot, or direct inventory gifts.spawn_story_note— Create readableBase.Notebookitems with custom multi-page lore/clues.spawn_zombie_horde— Spawn targeted zombie ambushes/hordes around coordinates or players.trigger_sound_or_alarm— Distant helicopter, gunshots, screams, or building alarms.set_weather— Dynamic storms, heavy rain, dense fog, or clear skies.spawn_vehicle— Spawn vehicles (good,wrecked, orrandom) with optional keys.trigger_world_effect— Fire, smoke, or explosion at coordinates.modify_player_status—heal_full,cure_infection(Build 42 safe),give_xp,calm_panic,induce_panic.schedule_zone_trigger/remove_zone_trigger— Deferred encounters that fire when survivors enter distant unloaded towns (radius10–90).get_kentucky_landmarks&search_game_catalog— Search vanilla Build 42 AND installed Workshop mod item/vehicle IDs.sync_mod_to_zomboid— Sync mod files into~/Zomboid/mods/ZomboidAIDirector.
Architecture
Project Zomboid (Lua, Kahlua2) Python MCP Server (stdio)
────────────────────────────── ─────────────────────────
~/Zomboid/Lua/AIDirector/state.json ──────► get_game_state()
~/Zomboid/Lua/AIDirector/cmd_index.txt ◄───── send_radio_transmission(), spawn_supply_drop(), ...
~/Zomboid/Lua/AIDirector/events.jsonl ──────► zone_trigger_fired / ack tracking
Quick Start
1. Install the Build 42 Mod
- From Steam Workshop: Subscribe to Project Zomboid AI Director (MCP Bridge) (Workshop ID
3840209384) and enableZomboidAIDirectorin Mods / ServerMods=. - Or from this repo: Run
uv run server.pyonce (it automatically copiesmod/ZomboidAIDirector/to~/Zomboid/mods/ZomboidAIDirector).
2. Run the MCP Server
Requires Python 3.12+ and uv:
cd pz-ai-director
uv sync
uv run server.py
3. Connect to Your AI Client
See ready-to-use templates in examples/mcp_configs/:
Environment Variables (Optional)
PZ_ZOMBOID_DIR— Override Zomboid user data folder (default:~/Zomboid).PZ_GAME_DIR— Override Project Zomboid Steam installation folder forsearch_game_catalog.
Running Tests
cd pz-ai-director
uv run python -m unittest discover -s tests -v
License
MIT — see LICENSE.