🎮 Godot MCP Server

AI-Powered Development Assistant for Godot Game Engine

English | 中文

Transform your Godot development with intelligent AI assistance

🤔 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

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

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

Note: Replace /path/to/your/godot/project with the actual path to your Godot project directory.

Alternative Installation Methods

npm install -g kooix-godot-mcp

Then use in Claude Desktop config:

{
  "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

| Tool | Description | Use Case | |------|-------------|----------| | get-project-info | Extract project configuration and metadata | Understanding project structure | | list-scenes | Analyze scene files and hierarchies | Scene management and organization | | analyze-scene | Deep analysis of specific scene files | Debugging scene-related issues | | list-scripts | Inventory all GDScript files | Code organization and refactoring | | analyze-script | Parse script structure and patterns | Code quality and optimization | | generate-script-template | Create common script patterns | Rapid development and consistency | | analyze-game-architecture | High-level architectural analysis | System design and planning | | generate-ui-component | Create UI component templates | Interface development | | optimize-game-performance | Performance analysis and suggestions | Game optimization | | generate-network-system | Networking code templates | Multiplayer development | | debug-project-errors | Error log analysis and solutions | Troubleshooting and debugging | | start-debug-session | Real-time debugging session | Interactive problem solving | | analyze-debug-logs | Parse and interpret log files | Post-mortem analysis | | get-performance-insights | Performance profiling and metrics | Optimization planning | | check-project-health | Overall project quality assessment | Maintenance and planning |

📖 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

Made with ❤️ for the Godot Community

Supercharge your game development with AI assistance