Skip to main content
Glama
pz-ai-director
by Aki-shin

Project Zomboid AI Director (Build 42 MCP Bridge)

Project Zomboid AI Director — 98.4 MHz Extraction Command

License: MIT Build 42 MCP

Русская версия (README.ru.md)

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): Registers Extraction 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_hud or strict_radio).

    • give_starter_radios — Equip players with tuned 98.4 MHz military walkie-talkies.

    • spawn_supply_drop — Drop crates with smoke flares, ground loot, or direct inventory gifts.

    • spawn_story_note — Create readable Base.Notebook items 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, or random) 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 (radius 10–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.

Related MCP server: minecraft-codex-companion

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 enable ZomboidAIDirector in Mods / Server Mods=.

  • Or from this repo: Run uv run server.py once (it automatically copies mod/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 for search_game_catalog.

Running Tests

cd pz-ai-director
uv run python -m unittest discover -s tests -v

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers