Project Zomboid MCP Server

An AI-powered MCP server for Project Zomboid mod development, offering script validation, generation, and contextual assistance.

A comprehensive Model Context Protocol (MCP) server for Project Zomboid mod development, providing intelligent script validation, generation, and contextual assistance through AI-enhanced tooling.

- Auto-detectionof Steam, Epic Games, and GOG installations
- Cross-platform support(Windows, Linux, macOS, WSL)
- Build 42 compatibilitywith modern mod structure support
- Fallback systemwith local script parsing

- Complete vanilla game indexingwith full-text search capabilities
- Rich metadata extractionincluding damage, durability, categories, and tags
- Relationship mappingbetween items, recipes, and dependencies
- Real-time reference validationagainst game database

- Template-based generationusing real game patterns
- Balance analysiscomparing custom items to vanilla equivalents
- Reference validationensuring all dependencies exist
- Multiple output formats(items, recipes, fixing scripts, sounds, vehicles)

- Real-time syntax validationwith detailed error reporting
- Reference checkingfor items, sounds, and sprites
- Balance analysiswith gameplay impact assessment
- Best practices suggestionsfor mod development

- Cloudflare Workerssupport for serverless deployment
- D1 Databaseintegration for persistent storage
- HTTP APIfor integration with any MCP client
- Claude Desktopready with example configurations

- Node.js 18.0.0 or higher
- npm or yarn package manager

# Clone the repository git clone https://github.com/minimax/pz-mcp-server.git cd pz-mcp-server # Install dependencies npm install # Build the project npm run build # Run in development mode npm run dev

# Install Wrangler CLI npm install -g wrangler # Login to Cloudflare wrangler login # Create D1 database wrangler d1 create pz-mcp-prod # Deploy to Cloudflare Workers wrangler deploy

Add to yourclaude_desktop_config.json:

{ "mcpServers": { "pz-mcp-server": { "command": "node", "args": ["/path/to/pz-mcp-server/dist/index.js"] } } }

The server can be integrated with any IDE that supports MCP protocol:
- Install the MCP extension for your IDE
- Configure the server endpoint
- Start using Project Zomboid development tools

Search vanilla Project Zomboid content with intelligent matching.

- query(string): Search query for game content
- type(string, optional): Filter by content type (item, recipe, sound, vehicle)
- category(string, optional): Filter by item category
- limit(number, optional): Maximum results (default: 20)

// Search for weapons await mcp.callTool('search_vanilla', { query: 'katana', type: 'item', category: 'Weapon' });

Generate balanced Project Zomboid scripts using templates and game data.

- type(string): Script type (item, recipe, evolvedrecipe, fixing, sound, vehicle)
- name(string): Name of the item/recipe to generate
- properties(object): Properties and specifications
- module(string, optional): Module name (default: "Base")

// Generate a custom weapon await mcp.callTool('generate_script', { type: 'item', name: 'SuperKatana', properties: { DisplayName: 'Super Katana', Type: 'Weapon', MaxDamage: 5.0, Weight: 2.0, Categories: 'LongBlade' } });

Validate Project Zomboid script syntax and references with detailed error reporting.

- content(string): Script content to validate
- type(string, optional): Expected script type
- strict(boolean, optional): Enable strict validation mode

// Validate mod script await mcp.callTool('validate_script', { content: scriptContent, type: 'item', strict: true });

Validate item, sound, and sprite references against game database.

- references(string[]): List of references to validate
- type(string, optional): Type of references (item, sound, sprite, all)

// Check if items exist await mcp.callTool('check_references', { references: ['Base.Katana', 'Base.Apple'], type: 'item' });

Comprehensive analysis of mod directory including balance, compatibility, and structure validation.

- modPath(string): Path to mod directory
- checkBalance(boolean, optional): Perform balance analysis
- checkCompatibility(boolean, optional): Check compatibility with vanilla
- generateReport(boolean, optional): Generate detailed analysis report

// Analyze mod quality await mcp.callTool('analyze_mod', { modPath: '/path/to/my-mod', checkBalance: true, checkCompatibility: true });

Parse and index Project Zomboid game files to populate the database.

- gamePath(string, optional): Path to Project Zomboid installation (auto-detected if not provided)
- forceReparse(boolean, optional): Force re-parsing even if data exists

// Parse vanilla game files await mcp.callTool('parse_game_files', { forceReparse: false });

┌─────────────────────────────────────────────────────┐ │ MCP Server Core │ ├─────────────────────────────────────────────────────┤ │ Path Manager │ Enhanced Parser │ Script Gen │ ├─────────────────────────────────────────────────────┤ │ SQLite/D1 Database Layer │ ├─────────────────────────────────────────────────────┤ │ Game Data │ Templates │ Validation │ │ (Vanilla PZ) │ (JSON-based) │ (Real-time) │ └─────────────────────────────────────────────────────┘

- DatabaseManager: SQLite/D1 database with full-text search capabilities
- ProjectZomboidParser: Parse vanilla game files and mod directories
- ScriptGenerator: Generate balanced scripts using templates and game data
- ValidationEngine: Real-time syntax and reference validation
- ModAnalyzer: Comprehensive mod analysis and quality metrics
- PathManager: Auto-detection of Project Zomboid installations

The server includes full Cloudflare Workers support for serverless deployment:

- D1 Databasefor persistent storage
- KV Storagefor caching frequently accessed data
- HTTP APIendpoints for all MCP tools
- Automatic scalingwith zero cold starts
- Global edge deploymentfor low latency

- GET /health- Health check
- GET /mcp/info- Server capabilities
- POST /tools/{toolName}- Execute MCP tools
- POST /admin/load-game-data- Load vanilla game data

Updatewrangler.tomlwith your database IDs:

[[env.production.d1_databases]] binding = "DB" database_name = "pz-mcp-prod" database_id = "your-database-id"

npm run dev # Server will auto-detect Project Zomboid installation

await mcp.callTool('parse_game_files', {});

// Search for existing items const results = await mcp.callTool('search_vanilla', { query: 'weapon damage > 3' }); // Generate new item const script = await mcp.callTool('generate_script', { type: 'item', name: 'MyWeapon', properties: { / ... / } }); // Validate before use const validation = await mcp.callTool('validate_script', { content: script });

- mod.info: Mod metadata and configuration
- Script Files (.txt): Items, recipes, vehicles, sounds, fixing scripts
- Lua Files (.lua): Game logic and event handlers
- Assets: Textures, sounds, models, and maps

// 1. Search for similar weapons const similarWeapons = await mcp.callTool('search_vanilla', { query: 'katana sword blade', type: 'item' }); // 2. Generate balanced weapon const weaponScript = await mcp.callTool('generate_script', { type: 'item', name: 'EliteKatana', properties: { DisplayName: 'Elite Katana', Type: 'Weapon', Weight: 2.5, MaxDamage: 4.5, MinDamage: 3.5, Categories: 'LongBlade', Icon: 'Katana', SwingSound: 'KatanaSwing' } }); // 3. Validate the script const validation = await mcp.callTool('validate_script', { content: weaponScript, strict: true }); // 4. Check references exist await mcp.callTool('check_references', { references: ['Katana', 'KatanaSwing'], type: 'all' });

const analysis = await mcp.callTool('analyze_mod', { modPath: '/path/to/my-zombie-mod', checkBalance: true, checkCompatibility: true, generateReport: true }); console.log(Mod Quality Score: ${analysis.quality.overall}/100); console.log(Issues Found: ${analysis.issues.length}); console.log(Recommendations: ${analysis.recommendations.join(', ')});

- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request

MIT License - see theLICENSEfile for details.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB