MCP 服务器

Godot Scene Analyzer

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.

README

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.