godot-mcp

Purpose

godot-mcp is a Model Context Protocol (MCP) server for the Godot game engine, used to let AI agents interact with Godot projects. Through this server, AI agents can launch the Godot editor, run projects, capture debug output, and control project execution, thereby establishing a direct feedback loop that helps agents judge how code runs in a real Godot project and improves the quality of code generation and debugging assistance.

Main capabilities

• Launch the Godot editor: Open the Godot editor for a specified project.
• Run a Godot project: Execute a Godot project in debug mode.
• Capture debug output: Obtain console output and error messages.
• Control execution: Start and stop Godot projects programmatically.
• Get the Godot version: Retrieve the installed Godot version.
• List Godot projects: Find Godot projects in a specified directory.
• Project analysis: Obtain detailed information about the project structure.
• Scene management:
  • Create a new scene with a specified root node type;
  • Add nodes with customizable properties to an existing scene;
  • Load sprites and textures into Sprite2D nodes;
  • Export a 3D scene as a MeshLibrary resource for use by GridMap;
  • Save scenes, with support for creating variants.
• UID management (for Godot 4.4+):
  • Get the UID of a specific file;
  • Update UID references by re-saving resources.

Usage

Prerequisites

• The Godot engine is installed on the system.
• Node.js (>=18.0.0) and npm.
• An AI agent that supports MCP.

Once the above conditions are met, restart Claude Code to use the Godot MCP tools.

Configuration

Configuration via environment variables is supported.

Cline: Add to the Cline MCP settings file (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json).

Cursor UI:

1. Go to Cursor Settings > Features > MCP;
2. Click the “+ Add New MCP Server” button;
3. Fill out the form: Name: godot, Type: command, Command: npx @coding-solo/godot-mcp;
4. You may need to click the refresh button in the upper right corner of the MCP server card to populate the tool list.

Project-level configuration: Create a .cursor/mcp.json file in the project directory.

Other MCP-compatible clients: The following configuration can be used:

Command: npx @coding-solo/godot-mcp

Environment variables

The MCP client can be pointed to build/index.jsinstead of using npx.

How it works

The Godot MCP server uses a bundled GDScript approach for complex operations:

• Direct commands: Simple operations such as launching the editor or getting project information directly use Godot's built-in CLI commands.
• Bundled operation script: Complex operations such as creating scenes or adding nodes use a single comprehensive GDScript file (godot_operations.gd) to handle all operations. This bundled script accepts an operation type and parameters (in JSON format), and can flexibly and dynamically execute operations without generating temporary files for each operation.

Use cases

Suitable for scenarios that require AI agents to interact directly with the Godot game engine, such as using AI to generate or debug Godot project code, automate scene and resource management, and obtain real-time debugging feedback during development.

Limitations and troubleshooting

• Godot not found: Set the GODOT_PATH environment variable to the path of the Godot executable.
• Connection issues: Make sure the server is running, and restart the AI assistant.
• Invalid project path: Make sure the path points to a directory containing the project.godot file.
• Build issues: Make sure you have run npm install Install all dependencies.
• In Cursor settings (Settings > MCP), confirm that the MCP server is displayed and enabled.
• MCP tools can only be run using the Agent chat profile (Cursor Pro or Business subscription).
• Use "Yolo Mode" to automatically run MCP tool requests.

License

This project is released under the MIT License, see the LICENSE file for details.