<p align="center"> <img src="https://img.shields.io/badge/Godot-4.x-478CBF?style=for-the-badge&logo=godotengine&logoColor=white" alt="Godot 4"> <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=for-the-badge" alt="MCP"> <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"> <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"> <img src="https://img.shields.io/badge/version-0.1.0-blue?style=for-the-badge" alt="Version"> </p>

Godot MCP

Control the Godot 4 editor from Claude Code (or any MCP client) via the Model Context Protocol.

Godot MCP is a bridge between AI assistants and the Godot 4 engine. It exposes 18 MCP tools + 3 editor-side endpoints that let you inspect scenes, create nodes, modify properties, capture screenshots, debug scripts, and manage project files — all without leaving your terminal.

Architecture

┌─────────────┐       stdio        ┌─────────────────┐      HTTP       ┌──────────────────┐
│  MCP Client │◄──────────────────►│  godot-mcp       │◄──────────────►│  Godot 4 Editor  │
│ (Claude Code)│                    │  (Python server) │  localhost:6789 │  (Editor Plugin) │
└─────────────┘                    └─────────────────┘                 └──────────────────┘

The system has two components:

1. MCP Server (Python) — Receives tool calls via stdio, translates them into HTTP requests
2. Editor Plugin (GDScript) — Runs inside Godot 4, exposes an HTTP API on 127.0.0.1:6789

Installation

1. Install the Python package

cd godot-mcp
pip install -e .

2. Install the Godot plugin

Copy the plugin folder into your Godot project:

cp -r godot_plugin/addons/godot_mcp /path/to/your/godot-project/addons/

Then in Godot: Project → Project Settings → Plugins → Enable "Godot MCP"

3. Configure Claude Code

Add to your Claude Code MCP settings (~/.claude.json or project config):

{
  "mcpServers": {
    "godot-mcp": {
      "command": "godot-mcp",
      "type": "stdio"
    }
  }
}

Available Tools

Tool	Description
get_editor_state	Get current editor state (open scenes, selected nodes)
get_scene_tree	Get the full scene tree hierarchy
get_node_properties	Get all properties of a specific node
set_node_property	Modify a node property in real-time
create_node	Create a new node (any Godot class) in the scene tree
delete_node	Remove a node from the scene tree
save_scene	Save the current scene to disk
run_scene	Run the current or a specific scene
stop_scene	Stop the running scene
execute_script	Execute GDScript code in editor context
get_project_files	List project files with glob pattern filtering
read_script	Read the contents of a GDScript file
write_script	Write or modify a GDScript file
get_viewport_screenshot	Capture the editor viewport as base64 PNG
get_logs	Get recent logs and errors from the Godot console
search_assets	Search the Godot Asset Library
download_asset	Download and install an asset from the Asset Library
preview_asset	Preview an image file from the project as base64 PNG

Editor-Side Endpoints (GDScript plugin)

These endpoints are available directly on the Godot HTTP server and can be accessed by the MCP tools internally:

Endpoint	Description
GET /editor/errors	Get filtered error messages from the editor error buffer
POST /script/check	Validate GDScript syntax without executing it
GET /editor/debugger	Get runtime debugger messages via MCPDebugCapture

Usage Example

Once both the Godot plugin is enabled and Claude Code is configured, you can interact with your Godot project naturally:

You: "Show me the scene tree of the current scene"
Claude: [calls get_scene_tree] → returns the full node hierarchy

You: "Move the Player node to position (100, 200)"
Claude: [calls set_node_property("Player", "position", "Vector2(100, 200)")]

You: "Run the game and check if it works"
Claude: [calls run_scene] → launches the scene in Godot

You: "Create a new script that makes the player jump"
Claude: [calls write_script("res://scripts/player.gd", "...GDScript code...")]

You: "Check my script for syntax errors"
Claude: [calls execute_script via /script/check] → returns compilation errors if any

You: "Show me the recent errors"
Claude: [calls get_logs(level="error")] → returns filtered error messages

Requirements

• Godot 4.x with the editor plugin enabled
• Python 3.10+
• Dependencies: mcp >= 1.0.0, httpx >= 0.27.0

Project Structure

godot-mcp/
├── src/godot_mcp/
│   ├── __init__.py
│   └── server.py            # MCP server (18 tools)
├── godot_plugin/addons/godot_mcp/
│   ├── plugin.cfg            # Plugin metadata
│   ├── plugin.gd             # Plugin entry point
│   └── godot_mcp_server.gd   # HTTP server + error tracking + debug capture
└── pyproject.toml

License

MIT