Custom Godot Scene Analyzer MCP Server

What It Is

An MCP (Model Context Protocol) server that gives Claude deep, semantic understanding of your Godot scenes—specifically designed to enforce and validate your ECS-driven architecture where Godot handles visuals and your custom ECS handles all game logic.

Not a generic scene reader. This server knows your architectural rules and actively helps you maintain separation between presentation and logic.

The Problem It Solves

Without This Server

You: "Check if any of my scenes have game logic in scripts"

Claude: "I'd need you to paste each .tscn file and script. Can you share them?"

You paste 30 files...

Claude: "In player.gd line 47, there's a velocity calculation. That might be game logic?"

Problems:

❌ Manual file dumping every time
❌ Claude guesses what's "game logic" vs "visual sync"
❌ No systematic validation across your project
❌ You maintain the rules in your head

With This Server

You: "Check if any of my scenes have game logic in scripts"

Claude: Automatically scans your Godot project, understands your ECS architecture rules, and provides:

✅ Instant analysis of all scenes
✅ Precise identification of architecture violations
✅ Clear distinction between valid visual sync code and improper game logic
✅ Systematic validation with your architectural rules built-in
✅ Actionable recommendations for fixes

Features

Architectural Enforcement

ECS-Aware Analysis: Understands the separation between Godot (presentation) and your ECS (logic)
Rule Validation: Automatically detects when scripts contain game logic that should be in ECS
Pattern Recognition: Distinguishes between acceptable visual synchronization code and architectural violations

Deep Scene Understanding

Scene Hierarchy Analysis: Maps node structures and relationships
Script Inspection: Analyzes attached GDScript files for logic patterns
Resource Tracking: Identifies dependencies and connections between scenes

Smart Reporting

Violation Detection: Flags scripts that break the ECS architecture
Context-Aware Suggestions: Provides specific guidance on moving logic to ECS
Project-Wide Insights: Summarizes architectural health across all scenes

How It Works

The MCP server integrates with Claude to provide:

Automatic Project Scanning: Reads your Godot project structure
Rule-Based Analysis: Applies your ECS architectural patterns
Semantic Understanding: Gives Claude context about what each scene does and how it fits your architecture
Interactive Queries: Answer questions about scenes without manual file sharing

Use Cases

Architecture Validation

"Are there any scenes violating the ECS pattern?" "Which scripts are doing game logic calculations?" "Show me all scenes that directly modify game state"

Refactoring Support

"Help me move the logic from player.gd to the ECS" "Which visual sync patterns am I using consistently?" "Find duplicate logic across scenes"

Code Review

"Review the enemy scenes for architecture compliance" "Check if the new UI scenes follow our patterns" "Validate that no scenes are managing their own state"

Installation

Requirements: Python 3.14 or higher

# Clone the repository git clone https://github.com/PurlieuStudios/godot-mcp.git cd godot-mcp # Verify Python version python --version # Should show Python 3.14.x # Create virtual environment python -m venv venv # Activate virtual environment # On Windows: venv\Scripts\activate # On macOS/Linux: source venv/bin/activate # Install dependencies pip install -e . # Configure for your Godot project python setup.py

Configuration

Create a .mcp-config.json in your Godot project root:

{ "projectPath": "/path/to/your/godot/project", "ecsRules": { "allowedVisualPatterns": [ "sync_position", "update_animation", "apply_visual_effect" ], "forbiddenLogicPatterns": [ "calculate_damage", "update_velocity", "manage_state", "ai_decision" ] } }

Usage with Claude

Once the MCP server is running, you can ask Claude:

"Analyze my Godot scenes for ECS compliance" "Show me which scripts need refactoring" "Help me understand the scene hierarchy for the combat system" "Are there any scripts doing physics calculations?"

Claude will automatically use the MCP server to access your project structure and provide informed, accurate answers based on your actual code.

Architecture Principles

This server enforces the following separation:

Godot Should Handle:

✅ Visual representation and rendering
✅ Animation playback
✅ Audio playback
✅ Input event routing
✅ Syncing visual state from ECS data

ECS Should Handle:

✅ Game state management
✅ Game logic and rules
✅ Physics and collision logic
✅ AI decisions
✅ Combat calculations

The Boundary:

Scripts attached to Godot nodes should only read from ECS and update visuals. They should never contain game logic or state management.

Benefits

For You

Maintain architectural consistency across your project
Catch violations early in development
Reduce cognitive load—let the server remember the rules
Faster code reviews and refactoring

For Claude

Deep understanding of your project structure
Accurate analysis without manual file sharing
Context-aware suggestions that respect your architecture
Ability to help with large-scale refactoring

Requirements

Python 3.14+
Godot 4.x project
Claude with MCP support

License

MIT

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ for developers who believe in clean architecture and the power of AI-assisted development.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Analyzes Godot game projects to enforce ECS architecture patterns, automatically detecting when scene scripts contain game logic that should be in the ECS layer and validating separation between presentation and logic code.

Godot Scene Analyzer