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:

1. Automatic Project Scanning: Reads your Godot project structure
2. Rule-Based Analysis: Applies your ECS architectural patterns
3. Semantic Understanding: Gives Claude context about what each scene does and how it fits your architecture
4. 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.