🤔 The Problem

Working with Godot can be challenging when you need to:

• ❌ Analyze complex project structures and scene hierarchies
• ❌ Debug cryptic error messages and performance issues
• ❌ Generate boilerplate code following Godot best practices
• ❌ Understand legacy codebases or inherited projects
• ❌ Optimize game performance without deep engine knowledge

✨ The Solution

Godot MCP Server bridges the gap between AI assistants and your Godot projects, providing:

• ✅ Intelligent Project Analysis: Deep understanding of your game architecture
• ✅ Smart Error Diagnosis: AI-powered debugging with actionable suggestions
• ✅ Code Generation: Templates and patterns following Godot conventions
• ✅ Performance Insights: Automated optimization recommendations
• ✅ Architecture Guidance: Best practices for scalable game development

🚀 Quick Start

Using npx (Recommended)

No installation required! Run directly:

npx kooix-godot-mcp --project /path/to/your/godot/project

Add to Claude Desktop

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["kooix-godot-mcp", "--project", "/path/to/your/godot/project"]
    }
  }
}

Alternative Installation Methods

npm install -g kooix-godot-mcp

{
  "mcpServers": {
    "godot-mcp": {
      "command": "godot-mcp",
      "args": ["--project", "/path/to/your/godot/project"]
    }
  }
}

npm install -g @telagod/kooix-godot-mcp

git clone https://github.com/telagod/kooix-godot-mcp.git
cd kooix-godot-mcp
npm install && npm run build
npm install -g .

🛠️ Features

📊 Project Intelligence

• Project Configuration: Extract settings, autoloads, and metadata
• Scene Architecture: Analyze node hierarchies and scene relationships
• Script Analysis: Parse GDScript for methods, properties, and signals
• Design Patterns: Identify architectural patterns and suggest improvements

🎨 Code Generation

• Smart Templates: Generate classes following Godot conventions
  • 🎯 Player Controllers with input handling
  • 🏗️ Manager Singletons for game systems
  • 🖼️ UI Components (Menus, Dialogs, HUD)
  • 🎮 Game Objects with lifecycle management

🌐 Network Systems

• Multiplayer Templates: Ready-to-use networking code
• REST API Integration: HTTP client implementations
• State Synchronization: Patterns for networked games

⚡ Performance Optimization

• Performance Profiling: Identify bottlenecks in your code
• Memory Management: Object pooling and resource optimization
• Best Practices: Automated code quality suggestions
• Performance Metrics: Real-time analysis of game systems

🐛 Debug & Troubleshooting

• Error Analysis: Intelligent parsing of Godot logs
• Crash Diagnostics: Root cause analysis for game crashes
• Performance Issues: Memory leaks and frame rate problems
• Code Quality: Static analysis and improvement suggestions

🎯 Use Cases

For Beginners

• 📚 Learn Godot best practices through generated examples
• 🔍 Understand existing project structures
• 🎓 Get explanations for complex game development concepts

For Experienced Developers

• 🚀 Accelerate development with smart code generation
• 🔧 Debug complex issues with AI-powered analysis
• 📈 Optimize performance with detailed recommendations
• 🏗️ Architect scalable game systems

For Teams

• 📋 Analyze and document legacy codebases
• 🔄 Maintain consistent coding standards
• 🤝 Onboard new team members faster
• 📊 Generate project health reports

🤖 Available Tools

📖 Documentation & Examples

Quick Examples

extends CharacterBody2D
class_name PlayerController

@export var speed: float = 300.0
@export var health: int = 100

signal health_changed(new_health: int)
signal player_died

var _input_vector: Vector2
var _is_alive: bool = true

func _ready() -> void:
    initialize_player()

func _process(delta: float) -> void:
    if _is_alive:
        handle_input()
        update_movement(delta)

# ... complete implementation generated

extends Control
class_name GameHUD

@export var health_bar: ProgressBar
@export var score_label: Label
@export var timer_label: Label

func update_health(health: int) -> void:
    if health_bar:
        health_bar.value = health

# ... complete HUD system with animations

Advanced Usage

• 🎯 Project Analysis Guide
• 🎨 Code Generation Examples
• ⚡ Performance Optimization
• 🐛 Debugging Workflows

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/telagod/kooix-godot-mcp.git
cd kooix-godot-mcp
npm install
npm run dev

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions