Summary

This repository provides the tomyud1/godot-mcp project, enabling AI assistants like Claude and Cursor to directly interact with the Godot game engine editor. It targets Godot 4.x developers seeking to accelerate their workflow by allowing AI to read, write, and manipulate scenes, scripts, nodes, and project settings without manual copy-pasting or context switching. The core benefit is a more integrated and efficient AI-assisted game development experience.

How It Works

The system employs a Machine Communication Protocol (MCP) server, built with Node.js, acting as an intermediary. An AI client (e.g., Claude Desktop, Cursor) communicates with the MCP server via standard input/output (stdio). The MCP server then establishes a WebSocket connection (port 6505) to a plugin within the Godot editor. This architecture facilitates direct AI control over editor functionalities. A novel interactive visualizer, accessible via HTTP on port 6510, provides a browser-based, force-directed graph of project scripts and their relationships, allowing real-time code editing and scene property manipulation that syncs directly with the Godot project.

Quick Start & Requirements

1. Install Node.js: Download and run the LTS installer from nodejs.org.
2. Install Godot Plugin: Within the Godot editor, navigate to the AssetLib tab, search for "Godot AI Assistant tools MCP," and install it. Enable the plugin under Project → Project Settings → Plugins.
3. Configure AI Client: Add the provided JSON server configuration to your AI client's settings (specific instructions for Claude Desktop, Cursor, and Claude Code are available).
4. Restart: Close and reopen your AI client, then restart your Godot project. A green "MCP Connected" indicator should appear in the Godot editor's top-right corner.

Prerequisites: Node.js (LTS), Godot 4.x, and an MCP-compatible AI client.

Highlighted Details

• Extensive Tooling: Offers 42 tools across six categories: File Operations, Scene Operations, Script Operations, Project Tools, Asset Generation, and Visualization.
• Interactive Visualizer: A browser-based project map and scene graph explorer allows for real-time code editing and node property adjustments.
• Direct Editor Access: AI can directly manipulate project files, scenes, nodes, scripts, and project settings.
• SVG to Sprite Generation: Includes a dedicated tool for generating 2D sprites from SVG assets.

Maintenance & Community

Release notes are documented in the release-notes/ directory, with a full change history available in CHANGELOG.md. No specific community links (Discord, Slack) or details on maintainers/sponsorships are provided in the README.

Licensing & Compatibility

The project is released under the MIT license. This license is permissive and generally allows for commercial use, modification, and distribution, including integration with closed-source projects.

Limitations & Caveats

The AI currently struggles with generating complex UI layouts, compositing scenes, and certain intricate node property manipulations. The system operates locally only, supporting a single Godot instance connection at a time, and lacks an undo feature, necessitating the use of version control for safety. The AI's knowledge of Godot is still developing, and it cannot autonomously create an entire game. The project is in active development, and user feedback is encouraged.