GoPeak

                           (((((((             (((((((                          
                        (((((((((((           (((((((((((                      
                        (((((((((((((       (((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
                 (((((((((((((((((((((((((((((((((((((((((((((((                
                        (((((((((((((((((((((((((((((((((                       
                                                                                

        /$$$$$$             /$$$$$$$                      /$$      
       /$$__  $$           | $$__  $$                    | $$      
      | $$  \__/  /$$$$$$ | $$  \ $$ /$$$$$$   /$$$$$$$ | $$  /$$/
      | $$ /$$$$//$$__  $$| $$$$$$$//$$__  $$ |____  $$ | $$ /$$/ 
      | $$|_  $$| $$  \ $$| $$____/| $$$$$$$$  /$$$$$$$ | $$$$$/  
      | $$  \ $$| $$  | $$| $$     | $$_____/ /$$__  $$ | $$  $$  
      |  $$$$$$/|  $$$$$$/| $$     |  $$$$$$ |  $$$$$$$ | $$\  $$ 
       \______/  \______/ |__/      \______/  \_______/ |__/ \__/ 

The most comprehensive Model Context Protocol (MCP) server for Godot Engine — enabling AI assistants to build, modify, and debug Godot games with unprecedented depth and precision.

Now with Auto Reload! Scenes and scripts automatically refresh in the Godot editor when modified externally via MCP.

Why GoPeak? The Game-Changing Benefits

🚀 Transform Your Game Development Workflow

GoPeak isn't just another tool — it's a paradigm shift in how AI assistants interact with game engines. Here's why this matters:

1. AI That Truly Understands Godot

Traditional AI assistants can write GDScript, but they're essentially working blind. They generate code based on training data, hoping it works. GoPeak changes everything:

• Real-time Feedback Loop: When you ask "run my project and show me errors," the AI actually runs your project, captures the output, and sees exactly what went wrong
• Context-Aware Assistance: The AI can inspect your actual scene tree, understand your node hierarchy, and provide suggestions based on your real project structure
• Validation Before Suggesting: Before suggesting you use a resource, the AI can verify it exists in your project

2. 95+ Tools with Dynamic ClassDB Introspection

Instead of hardcoding tools for every Godot class, GoPeak provides generic tools (add_node, create_resource) that work with ANY ClassDB class, plus ClassDB introspection tools that let AI discover classes, properties, and methods dynamically.

Design Philosophy: Rather than providing 90+ specialized tools (e.g., create_camera, create_light, create_physics_material), GoPeak uses generic add_node and create_resource tools that work with ANY Godot class. The AI uses query_classes to discover available types and query_class_info to learn their properties — just like a developer using the Godot docs.

3. Seamless Editor Integration with Auto Reload

The included Auto Reload plugin eliminates the friction of external editing:

• No Manual Refresh: When MCP modifies a scene or script, the Godot editor automatically reloads it
• 1-Second Detection: Lightweight polling with negligible performance impact (~0.01ms/sec)
• Smart Watching: Monitors open scenes AND their attached scripts
• Zero Configuration: Just enable the plugin and forget about it

MCP modifies file → Auto Reload detects change → Editor reloads → You see the result instantly

4. Eliminate the Copy-Paste-Debug Cycle

Before GoPeak:

1. Ask AI for code
2. Copy code to your project
3. Run project, encounter error
4. Copy error back to AI
5. Get fix, paste it
6. Repeat 10+ times

With GoPeak:

1. "Create a player character with health, movement, and jumping"
2. AI creates the scene, writes the script, adds the nodes, connects signals, and tests it
3. Done.

The AI doesn't just write code — it implements features end-to-end.

5. Type-Safe, Error-Resistant Operations

Every operation in GoPeak includes:

• Path Validation: Prevents invalid file operations
• Type Serialization: Correctly handles Vector2, Vector3, Color, Transform, and all Godot types
• Error Recovery: Meaningful error messages with suggested fixes
• Atomic Operations: Changes are applied consistently or not at all

Example: When you ask to set a node's position, GoPeak:

1. Validates the scene exists
2. Validates the node path
3. Deserializes {"x": 100, "y": 200} to Vector2(100, 200)
4. Sets the property
5. Saves the scene
6. Confirms success or reports exactly what went wrong

6. Project Health Intelligence

The get_project_health tool provides a comprehensive analysis of your project:

{
  "score": 85,
  "grade": "B",
  "checks": {
    "structure": { "passed": true },
    "resources": { "issues": ["3 textures need reimporting"] },
    "scripts": { "issues": ["5 TODO comments found"] },
    "config": { "passed": true }
  },
  "recommendations": [
    "Configure export presets for your target platforms",
    "Review and resolve TODO items before release"
  ]
}

This turns your AI assistant into a code reviewer that actually understands your Godot project.

7. Dependency Analysis & Circular Reference Detection

Ever had a project break because of circular dependencies? The get_dependencies tool:

• Maps every resource dependency in your project
• Detects circular references before they cause runtime errors
• Shows you the complete dependency chain for any resource

PlayerScene.tscn
├── PlayerScript.gd
│   └── WeaponBase.gd
│       └── ⚠️ CIRCULAR: PlayerScript.gd
└── PlayerSprite.png

8. Live Runtime Debugging (Optional Addon)

Install the included godot_mcp_runtime addon and unlock:

• Live Scene Tree Inspection: See your game's actual node tree while it runs
• Hot Property Modification: Change values in real-time without restarting
• Remote Method Calling: Trigger functions in your running game
• Performance Monitoring: Track FPS, memory, draw calls, and more

This transforms debugging from "add print statements and restart" to "inspect and modify on the fly."

💡 Real-World Use Cases

Rapid Prototyping

"Create a basic platformer with a player that can move, jump, and collect coins"

The AI creates scenes, scripts, nodes, signals, and input actions — a playable prototype in minutes.

Refactoring at Scale

"Find all uses of the old PlayerData resource and update them to use the new PlayerStats"

Search the entire project, identify every reference, and make consistent changes.

Debugging Complex Issues

"My player keeps falling through the floor. Check my collision setup and tell me what's wrong"

Inspect node properties, analyze scene structure, and identify configuration issues.

Learning Godot

"Show me how signals work by creating a button that changes a label's text when clicked"

Instead of just explaining, the AI builds a working example in your actual project.

Maintaining Large Projects

"Run a health check on my project and tell me what needs attention"

Get actionable insights about project structure, unused resources, and potential issues.

Features

Core Features

• Launch Godot Editor: Open the Godot editor for a specific project
• Run Godot Projects: Execute Godot projects in debug mode
• Capture Debug Output: Retrieve console output and error messages
• Control Execution: Start and stop Godot projects programmatically
• Get Godot Version: Retrieve the installed Godot version
• List Godot Projects: Find Godot projects in a specified directory
• Project Analysis: Get detailed information about project structure

Scene Management

• Create new scenes with specified root node types
• Add, delete, duplicate, and reparent nodes
• Set node properties with type-safe serialization
• List scene tree structure with full hierarchy
• Load sprites and textures into Sprite2D nodes
• Export 3D scenes as MeshLibrary resources for GridMap

GDScript Operations

• Create Scripts: Generate new GDScript files with templates (singleton, state_machine, component, resource)
• Modify Scripts: Add functions, variables, and signals to existing scripts
• Analyze Scripts: Get detailed information about script structure, dependencies, and exports

Signal & Connection Management

• Connect signals between nodes in scenes
• Disconnect signal connections
• List all signal connections in a scene

ClassDB Introspection (New!)

• Query Classes: Discover available Godot classes with filtering by name, category (node, node2d, node3d, control, resource, etc.), and instantiability
• Query Class Info: Get detailed methods, properties, signals, and enums for any class
• Inspect Inheritance: Explore class hierarchy — ancestors, children, and all descendants

Resource Management

• Create Resources: Generate ANY resource type as .tres files (replaces specialized create_* tools)
• Modify Resources: Update properties of existing .tres/.res files
• Create Materials: StandardMaterial3D, ShaderMaterial, CanvasItemMaterial, ParticleProcessMaterial
• Create Shaders: canvas_item, spatial, particles, sky, fog shaders with templates

Animation System

• Create new animations in AnimationPlayer nodes
• Add property and method tracks to animations
• Insert keyframes with proper value serialization

2D Tile System

• Create TileSet resources with atlas texture sources
• Set TileMap cells programmatically

Import/Export Pipeline

• Get import status and options for resources
• Modify import settings and trigger reimport
• List export presets and validate project for export
• Export projects using Godot CLI

Project Configuration

• Get and set project settings
• Manage autoload singletons (add, remove, list)
• Set main scene
• Add input actions with key, mouse, and joypad events

Plugin Management

• List installed plugins with status
• Enable and disable plugins

Developer Experience

• Dependency Analysis: Get resource dependency graphs with circular reference detection
• Resource Usage Finder: Find all usages of a resource across the project
• Error Log Parser: Parse Godot error logs with suggestions
• Project Health Check: Comprehensive project analysis with scoring
• Project Search: Search for text/patterns across all project files

Runtime Connection (Optional Addon)

• Real-time scene tree inspection
• Live property modification
• Remote method calling
• Performance metrics monitoring
• Signal watching

Screenshot Capture (New!)

• Capture the running game's viewport as a base64 PNG/JPG image
• Specify target resolution for resized captures
• Capture specific viewports by node path

Input Injection (New!)

• Simulate Godot input actions (press/release) for automated testing
• Inject keyboard key events with modifier support (Shift, Ctrl, Alt)
• Simulate mouse clicks (left/right/middle, single/double)
• Simulate mouse movement (absolute and relative)

GDScript Language Server (New!)

• Get real-time diagnostics (errors/warnings) from Godot's built-in LSP
• Code completions at any position in a GDScript file
• Hover information for symbols, functions, and variables
• Document symbol outlines for navigation
• Lazy connection to Godot editor's LSP (port 6005)

Debug Adapter Protocol (New!)

• Capture debug console output from running Godot games
• Set and remove breakpoints in GDScript files
• Step over, continue, and pause execution
• Inspect stack traces at breakpoints
• Lazy connection to Godot's built-in DAP (port 6006)

MCP Resources (New!)

• Access Godot project files via godot:// URI protocol
• godot://project/info — parsed project.godot metadata as JSON
• godot://scene/{path} — read .tscn scene files
• godot://script/{path} — read .gd script files
• godot://resource/{path} — read .tres/.tscn/.gd files
• Path traversal protection built-in

UID Management (Godot 4.4+)

• Get UID for specific files
• Update UID references by resaving resources

Multi-Source Asset Library (CC0)

• Unified Search: Search for 3D models, textures, HDRIs across multiple CC0 asset providers
• Automatic Download: Fetch assets directly into your Godot project
• Provider Priority: Searches Poly Haven → AmbientCG → Kenney in order
• Attribution Tracking: Automatic CREDITS.md generation for proper attribution

Supported Providers:

Requirements

• Godot Engine 4.x installed on your system
• Node.js 18+ and npm
• An AI assistant that supports MCP (Claude Desktop, Cline, Cursor, OpenCode, etc.)

Installation and Configuration

🚀 One-Click Install (Recommended)

Linux / macOS

curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash

This script will:

• ✅ Check prerequisites (Git, Node.js 18+, npm)
• ✅ Clone the repository to ~/.local/share/godot-mcp
• ✅ Install dependencies and build automatically
• ✅ Auto-detect Godot installation
• ✅ Show configuration instructions for your AI assistant

Advanced Options:

# Custom installation directory
curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --dir ~/my-godot-mcp

# Specify Godot path
curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --godot /usr/bin/godot4

# Get configuration for specific AI assistant
curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --configure claude

Available options:

Install via npm (Fastest)

npx gopeak

Or install globally:

npm install -g gopeak
gopeak

Then configure your AI assistant to run gopeak (or npx gopeak) instead of node /path/to/build/index.js.

Manual Installation

Step 1: Install and Build

git clone https://github.com/HaD0Yun/godot-mcp.git
cd godot-mcp
npm install
npm run build

Step 2: Configure with Your AI Assistant

Option A: Configure with Cline (VS Code)

Add to your Cline MCP settings file:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      },
      "disabled": false
    }
  }
}

Option B: Configure with Cursor

1. Go to Cursor Settings > Features > MCP
2. Click + Add New MCP Server
3. Name: godot, Type: command
4. Command: node /absolute/path/to/godot-mcp/build/index.js

Option C: Configure with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/path/to/godot"
      }
    }
  }
}

Option D: Configure with OpenCode

Add to your opencode.json:

{
  "mcp": {
    "godot": {
      "type": "local",
      "command": ["node", "/absolute/path/to/godot-mcp/build/index.js"],
      "enabled": true,
      "environment": {
        "GODOT_PATH": "/path/to/godot"
      }
    }
  }
}

Step 3: Environment Variables

Example Prompts

Once configured, you can use natural language to control Godot:

Scene Building

"Create a new scene with a CharacterBody2D root node called Player"
"Add a Sprite2D and CollisionShape2D to my Player scene"
"Duplicate the Enemy node and name it Enemy2"

Script Operations

"Create a GDScript for my player with movement and jumping"
"Add a take_damage function to my player script that emits a health_changed signal"
"Show me the structure of my PlayerController script"

Resource Management

"Create a red StandardMaterial3D for my enemy"
"Create a canvas_item shader with a dissolve effect"
"Generate a TileSet from my tilemap_atlas.png with 16x16 tiles"
"Modify the environment resource to enable fog and glow"

ClassDB Discovery

"What 3D light types are available in Godot?"
"Show me all properties of CharacterBody3D"
"What classes inherit from Control?"
"Find all instantiable physics body types"

Project Analysis

"Check my project health and show me any issues"
"Find all files that use the PlayerData resource"
"Show me the dependency graph for my main scene"
"Search my project for 'TODO' comments"

Configuration

"Add a 'jump' input action mapped to Space and gamepad button 0"
"Register my GameManager script as an autoload singleton"
"Set the main scene to res://scenes/main_menu.tscn"

Debugging

"Run my project and show me any errors"
"Parse my Godot error log and suggest fixes"
"Inspect the scene tree of my running game"

Asset Library

"Search for a chair model across all asset sources"
"Find rock textures from AmbientCG"
"Download the nature-kit asset pack from Kenney"
"List all available asset providers"

Screenshot & Input

"Take a screenshot of the running game"
"Press the jump action and capture the result"
"Click at position (400, 300) in the game"
"Simulate pressing the W key"

GDScript Analysis (LSP)

"Check my player script for errors using the language server"
"Get code completions at line 25 in movement.gd"
"Show me hover info for the 'velocity' variable"
"Get the symbol outline for my main script"

Debug Adapter

"Set a breakpoint at line 42 in player.gd"
"Show me the stack trace"
"Continue execution after the breakpoint"
"Get the debug console output"

Included Addons

Auto Reload Plugin (Recommended)

Essential for MCP workflow - automatically reloads scenes and scripts when modified externally.

Installation

Option 1: One-Click Install

Linux / macOS (Bash)

# Run in your Godot project folder
curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash

Windows (PowerShell)

# Run in your Godot project folder
irm https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 | iex

Option 2: Manual Install

1. Copy build/addon/auto_reload to your project's addons/ folder
2. Open your project in Godot
3. Go to Project > Project Settings > Plugins
4. Enable "Godot MCP Auto Reload"

How It Works

[1 sec polling] → Check file modification times → Reload changed files

Output Messages

[Godot MCP - AutoReload] Plugin activated - watching for external changes
[Godot MCP - AutoReload] Scene changed: res://scenes/player.tscn
[Godot MCP - AutoReload] Scene reloaded: res://scenes/player.tscn

Warning

Data Loss Risk: If you modify a scene in the editor AND externally at the same time, editor changes will be lost.

Best Practice:

• Use MCP for modifications
• Use Godot editor for viewing/testing only
• Save before external modifications

Runtime Addon (Optional)

For live debugging features, install the runtime addon:

1. Copy build/addon/godot_mcp_runtime to your project's addons/ folder
2. Enable in Project Settings > Plugins
3. The addon starts a TCP server on port 7777 when your game runs

Runtime Tools:

• get_runtime_status - Check if game is running
• inspect_runtime_tree - View live scene tree
• set_runtime_property - Modify properties in real-time
• call_runtime_method - Invoke methods remotely
• get_runtime_metrics - Monitor FPS, memory, draw calls
• capture_screenshot - Capture viewport as base64 image
• capture_viewport - Capture specific viewport texture
• inject_action / inject_key / inject_mouse_click / inject_mouse_motion - Input simulation

Complete Tool Reference

Core Tools (7)

Scene Tools (9)

Script Tools (3)

ClassDB Introspection Tools (3)

Resource Tools (7)

Animation Tools (2)

Signal Tools (3)

Import/Export Tools (7)

Configuration Tools (7)

Plugin Tools (3)

DX Tools (5)

Runtime Tools (5)

UID Tools (2)

Asset Library Tools (3)

Screenshot Tools (2)

Input Injection Tools (4)

GDScript LSP Tools (4)

DAP (Debug) Tools (7)

Architecture

GoPeak uses a hybrid architecture:

1. Direct CLI Commands: Simple operations use Godot's built-in CLI
2. Bundled GDScript: Complex operations use a comprehensive godot_operations.gd script with ClassDB introspection
3. Runtime Addon: TCP server (port 7777) for live debugging, screenshot capture, and input injection
4. Godot LSP Integration: Connects to Godot editor's Language Server (port 6005) for GDScript diagnostics
5. Godot DAP Integration: Connects to Godot editor's Debug Adapter (port 6006) for breakpoints and stepping
6. MCP Resources: godot:// URI protocol for direct project file access

Key Design Decisions:

• ClassDB-based dynamic approach: Instead of hardcoding tools for every Godot class, generic tools (add_node, create_resource) work with ANY class. AI discovers capabilities via query_classes and query_class_info
• Type-safe serialization: Automatic conversion for Vector2, Vector3, Color, Rect2, NodePath, and other Godot types
• No temporary files: Everything runs through the bundled GDScript operations dispatcher
• Consistent error handling: All operations validate inputs and provide meaningful error messages

Troubleshooting

Contributing

Contributions are welcome! Please read the CONTRIBUTING.md guide.

License

MIT License - see LICENSE for details.

Stats

• 95+ Tools — comprehensive tools covering scene management, scripting, resources, animation, configuration, debugging, screenshots, input injection, LSP, DAP, and asset management
• MCP Resources — godot:// URI protocol for direct project file access
• GDScript LSP — real-time diagnostics, completions, hover, and symbols via Godot's Language Server
• Debug Adapter (DAP) — breakpoints, stepping, stack traces, and console output capture
• Screenshot Capture — viewport capture from running games via runtime addon
• Input Injection — keyboard, mouse, and action simulation for automated testing
• ClassDB Introspection — AI dynamically discovers Godot classes, properties, and methods instead of relying on hardcoded tool definitions
• 20,000+ lines of TypeScript and GDScript
• ~85% coverage of Godot Engine's capabilities
• Godot 4.x full support (including 4.4+ UID features)
• Auto Reload plugin for seamless MCP integration
• Multi-Source Asset Library with CC0 assets from Poly Haven, AmbientCG, and Kenney
• npm package — install with npx gopeak or npm install -g gopeak

Credits

• Original MCP server by Coding-Solo
• Auto Reload plugin and unified package by HaD0Yun