MCP 服务器

godot-mcp

Bridges AI assistants with the Godot 4 editor, exposing tools to inspect scenes, create nodes, modify properties, capture screenshots, debug scripts, and manage project files via the Model Context Protocol.

README

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:

MCP Server (Python) — Receives tool calls via stdio, translates them into HTTP requests
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