Godot MCP Server

A comprehensive Model Context Protocol (MCP) server for Godot Engine that enables AI assistants to interact with Godot projects. Provides powerful tools for project management, script execution, scene manipulation, asset management, and more.

Features

• 🚀 Project Management - Launch editor, run projects, manage multiple projects
• 📜 Script Management - Create, read, analyze GDScript with templates
• 🎬 Scene Management - List, inspect, create scenes
• 🔍 Node Operations - Find nodes, get properties
• 📊 Project Analysis - Statistics, unused assets detection
• 🎨 Asset Management - List images, audio, fonts
• ⚙️ Project Settings - Read project.godot configuration
• ✅ Validation - GDScript validation via LSP
• 📦 Export - Export to Windows, Linux, macOS, Android, Web
• 🔧 UID Management - Godot 4.4+ UID support

Requirements

• Node.js 18+
• Godot Engine 4.x (recommended)
• npm

Quick Start

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

Configuration

Environment Variables

Variable	Description	Default
GODOT_PATH	Path to Godot executable	Auto-detected
GODOT_PROJECT_PATH	Path to Godot project	Current directory
GODOT_LSP_PORT	LSP port	6005
DEBUG	Enable debug logging	false

Claude Desktop

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

Cline

See configs/cline_mcp_settings.json for full auto-approve list.

Cursor

Create .cursor/mcp.json in your project:

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

Available Tools (35+)

Project Management

Tool	Description
godot_launch_editor	Launch Godot editor
godot_run_project	Run project (debug/headless)
godot_stop_project	Stop running project
godot_get_project_info	Get project details
godot_get_version	Get Godot version
godot_list_projects	Find projects in directory
godot_quit	Quit Godot

Script Management

Tool	Description
godot_list_scripts	List all .gd files
godot_read_script	Read script content
godot_create_script	Create with template
godot_analyze_script	Analyze for issues
godot_run_script	Execute script file
godot_run_code	Execute inline code

Scene Management

Tool	Description
godot_list_scenes	List all .tscn files
godot_get_scene_tree	Get node hierarchy
godot_create_scene	Create new scene
godot_save_scene	Save current scene

Node Operations

Tool	Description
godot_find_nodes	Find nodes by name/type
godot_get_node_properties	Get node properties

UID Management (Godot 4.4+)

Tool	Description
godot_get_uid	Get UID for a file
godot_update_project_uids	Update UID references

Debug

Tool	Description
godot_get_debug_output	Capture debug output

Project Analysis

Tool	Description
godot_analyze_project	Get project statistics
godot_find_unused_assets	Find unused assets

Asset Management

Tool	Description
godot_list_resources	List .tres files
godot_list_assets	List images, audio, fonts

Project Settings

Tool	Description
godot_get_project_settings	Read project.godot

Validation

Tool	Description
godot_validate_script	Validate via LSP
godot_check_lsp	Check LSP connection

Export

Tool	Description
godot_export_project	Export to platform
godot_get_export_presets	List export presets

Utility

Tool	Description
godot_execute	Arbitrary command
godot_get_config	Get configuration

Script Templates

When creating scripts, use the template parameter:

• basic - Basic Node script
• node - Node with @onready
• character - CharacterBody2D with movement
• resource - Custom Resource
• autoload - Autoload singleton
• state - State pattern

Example Prompts

"Launch the Godot editor for my project"
"Create a Player script with character template"
"Analyze my project and show statistics"
"Find all scenes in my project"
"Export my project for Windows"
"What scripts are in my project?"
"Get the scene tree of Main.tscn"

Development

npm run dev    # Development with hot reload
npm run build  # Build TypeScript
npm start      # Run production

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to help improve the project.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

MIT - See LICENSE