Content
# Godot MCP Server
[English](./README_EN.md) | 中文
A Model Context Protocol (MCP) server plugin designed for the Godot Engine, enabling AI assistants to interact directly with the Godot editor for AI-driven game development.
## Features
### Core Features
- **Scene Management** - Create, open, save scenes, view scene tree structure
- **Node Operations** - Add, delete, move nodes, modify node properties
- **Script Editing** - Create, read, modify GDScript scripts
- **Resource Management** - Load, create, modify game resources
- **File System** - Browse project files, read and write file content
- **Editor Control** - Control the editor interface, manage selected objects, undo/redo
- **Debugging Tools** - View logs, get runtime information
- **Animation Tools** - Create and edit animations, state machine management
### Visual Effects
- **Material Tools** - Create and configure materials
- **Shader Tools** - Manage shader parameters
- **Lighting Tools** - Configure scene lighting
- **Particle Tools** - Create particle effects
### 2D Development
- **TileMap Tools** - TileMap editing and configuration
- **Geometry Tools** - 2D geometry creation
### Gameplay
- **Physics Tools** - Physics body and collision configuration
- **Navigation Tools** - Navigation mesh and pathfinding
- **Audio Tools** - Audio playback and configuration
### Utility Tools
- **UI Tools** - User interface components
- **Signal Tools** - Signal connection management
- **Grouping Tools** - Node grouping management
### Multilingual Support
The plugin interface supports 9 languages, automatically detecting the system language:
- English
- 简体中文
- 繁體中文
- 日本語 (日语)
- Русский (俄语)
- Français (法语)
- Português (葡萄牙语)
- Español (西班牙语)
- Deutsch (德语)
## Supported AI Clients
### IDE Editors (One-Click Configuration)
- **Trae CN** - AI Editor Chinese Version
- **Cursor** - AI Code Editor
- **Windsurf** - Codeium's AI Editor
### CLI Command-Line Tools (Command Copy)
- **Claude CLI** - Anthropic Claude Command-Line Tool
- **Codex CLI** - OpenAI Codex Command-Line Tool
- **Gemini CLI** - Google Gemini Command-Line Tool
## System Requirements
- Godot Engine 4.x
- Supported operating systems: Windows, macOS, Linux
## Installation Steps
1. Download or clone this repository:
```bash
git clone https://github.com/DaxianLee/godot-mcp.git
```
2. Copy the `addons/godot_mcp` folder to the `addons` directory of your Godot project:
```
your_project/
├── addons/
│ └── godot_mcp/
│ ├── plugin.cfg
│ ├── plugin.gd
│ ├── mcp_server.gd
│ ├── i18n/
│ └── tools/
└── ...
```
3. In the Godot editor, open `Project -> Project Settings -> Plugins`
4. Find **Godot MCP Server** and enable it
## Usage Tutorial
### 1. Start the MCP Server
After the plugin is enabled, you will see the **GodotMCP** panel on the right side of the editor:
- **Server** - Displays the server running status, endpoint address, and author information
- **Tools** - Manages available MCP tools (displayed by category)
- **Configuration** - One-click configuration for IDEs and command copy for CLIs
Default configuration:
- Port: `3000`
- Address: `http://127.0.0.1:3000/mcp`
- Auto-start: Enabled
### 2. Configure the AI Client
#### IDE Editors - One-Click Configuration
Switch to the "Configuration" tab in the GodotMCP panel to see the supported IDE clients.
##### Trae CN
1. Click the "One-Click Configuration" button under Trae CN
2. Restart Trae CN
Configuration file location:
- **macOS**: `~/Library/Application Support/Trae CN/User/mcp.json`
- **Windows**: `%APPDATA%\Trae CN\User\mcp.json`
- **Linux**: `~/.config/Trae CN/User/mcp.json`
##### Cursor
1. Click the "One-Click Configuration" button under Cursor
2. Restart Cursor
Configuration file location: `~/.cursor/mcp.json`
##### Windsurf
1. Click the "One-Click Configuration" button under Windsurf
2. Restart Windsurf
Configuration file location: `~/.codeium/windsurf/mcp_config.json`
#### CLI Command-Line Tools - Copy Command
CLI tools require executing commands in the terminal for configuration. In the "Configuration" tab:
1. Use the "Configuration Scope" dropdown to select the scope:
- **User-level** - Globally effective, usable in all projects
- **Project-level** - Only effective for the current project
2. Copy the command for the corresponding tool and execute it in the terminal
##### Claude CLI (Claude Code)
```bash
claude mcp add --scope <user|project> --transport http godot-mcp http://127.0.0.1:3000/mcp
```
##### Codex CLI
```bash
codex mcp add --scope <user|project> --transport http godot-mcp http://127.0.0.1:3000/mcp
```
##### Gemini CLI
```bash
gemini mcp add --scope <user|project> --transport http godot-mcp http://127.0.0.1:3000/mcp
```
### 3. Start Using
After configuration, you can directly manipulate the Godot project in the AI client:
```
User: Help me create a new scene and add a Sprite2D node
AI: Okay, I'll create the scene for you...
[Calling scene_create to create the scene]
[Calling node_add to add the Sprite2D node]
Done! A new scene containing the Sprite2D node has been created.
```
## Tool List
### Core Tools
#### Scene Tools (Scene)
| Tool Name | Description |
|--------|------|
| `scene_create` | Create a new scene |
| `scene_open` | Open the specified scene |
| `scene_save` | Save the current scene |
| `scene_get_tree` | Get the scene tree structure |
| `scene_get_current` | Get the current scene information |
#### Node Tools (Node)
| Tool Name | Description |
|--------|------|
| `node_add` | Add a new node |
| `node_delete` | Delete a node |
| `node_get` | Get node information |
| `node_set_property` | Set node properties |
| `node_get_property` | Get node properties |
| `node_move` | Move node position |
| `node_rename` | Rename a node |
| `node_duplicate` | Duplicate a node |
| `node_find` | Find a node |
#### Script Tools (Script)
| Tool Name | Description |
|--------|------|
| `script_create` | Create a new script |
| `script_read` | Read script content |
| `script_write` | Write script content |
| `script_attach` | Attach a script to a node |
#### Resource Tools (Resource)
| Tool Name | Description |
|--------|------|
| `resource_load` | Load a resource |
| `resource_create` | Create a resource |
| `resource_save` | Save a resource |
#### Filesystem Tools (Filesystem)
| Tool Name | Description |
|--------|------|
| `filesystem_list` | List directory contents |
| `filesystem_read` | Read a file |
| `filesystem_write` | Write to a file |
| `filesystem_delete` | Delete a file |
#### Project Tools (Project)
| Tool Name | Description |
|--------|------|
| `project_get_info` | Get project information |
| `project_get_settings` | Get project settings |
#### Editor Tools (Editor)
| Tool Name | Description |
|--------|------|
| `editor_get_selection` | Get the current selection |
| `editor_select_node` | Select the specified node |
| `editor_undo_redo` | Undo/redo operation |
#### Debug Tools (Debug)
| Tool Name | Description |
|--------|------|
| `debug_get_logs` | Get debug logs |
#### Animation Tools (Animation)
| Tool Name | Description |
|--------|------|
| `animation` | Create and edit animations |
| `animation_state_machine` | State machine management |
### Visual Tools
#### Material Tools (Material)
| Tool Name | Description |
|--------|------|
| `material` | Create and configure materials |
#### Shader Tools (Shader)
| Tool Name | Description |
|--------|------|
| `shader` | Shader parameter management |
#### Lighting Tools (Lighting)
| Tool Name | Description |
|--------|------|
| `lighting` | Scene lighting configuration |
#### Particle Tools (Particle)
| Tool Name | Description |
|--------|------|
| `particle` | Particle effect creation |
### 2D Tools
#### TileMap Tools (TileMap)
| Tool Name | Description |
|--------|------|
| `tilemap` | TileMap editing |
#### Geometry Tools (Geometry)
| Tool Name | Description |
|--------|------|
| `geometry` | 2D geometry graphics |
### Gameplay Tools
#### Physics Tools (Physics)
| Tool Name | Description |
|--------|------|
| `physics` | Physics body and collision configuration |
#### Navigation Tools (Navigation)
| Tool Name | Description |
|--------|------|
| `navigation` | Navigation mesh and pathfinding |
#### Audio Tools (Audio)
| Tool Name | Description |
|--------|------|
| `audio` | Audio playback and configuration |
### Utility Tools
#### UI Tools
| Tool Name | Description |
|--------|------|
| `ui` | User interface components |
#### Signal Tools (Signal)
| Tool Name | Description |
|--------|------|
| `signal` | Signal connection management |
#### Group Tools (Group)
| Tool Name | Description |
|--------|------|
| `group` | Node grouping management |
## FAQ
### Q: The server cannot start?
A: Check if the port is occupied and try restarting after changing the port.
### Q: The AI client cannot connect?
A:
1. Make sure the MCP server is running (status is displayed as green)
2. Check if the port number in the configuration file is correct
3. Restart the AI client
### Q: What do I need to do after changing the port?
A: You need to update the port number in the AI client's configuration file and then restart the client.
### Q: How to switch the interface language?
A: In the settings area of the "Server" tab, use the "Language" dropdown to select the language you need.
## License
This project uses a **Non-Commercial Use License**.
### Allowed:
- Personal learning and research use
- Non-commercial open-source project use
- Educational and teaching purposes
### Prohibited:
- Commercial use (including but not limited to sales, integration into commercial products)
- Unauthorized redistribution
For commercial use authorization, please contact the author.
## Author
**LIDAXIAN**
- GitHub: [https://github.com/DaxianLee/godot-mcp](https://github.com/DaxianLee/godot-mcp)
- WeChat: `lidaxian-AI`
## Contributing
Welcome to submit Issues and Pull Requests!
1. Fork this repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## Acknowledgments
- [Godot Engine](https://godotengine.org/) - Open-source game engine
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI interaction protocol specification
---
If this project is helpful to you, please give a Star!
