Content
# Godot MCP Server
[English](./README_EN.md) | English
A Model Context Protocol (MCP) server plugin designed for the Godot engine, allowing AI assistants to interact directly with the Godot editor for AI-driven game development.
## Features
### Core Features
- **Scene Management** - Create, open, save scenes, and view scene tree structure
- **Node Operations** - Add, delete, move nodes, and 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 contents
- **Editor Control** - Control the editor interface, manage selected objects, undo and 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 geometric figure 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
- **Group Tools** - Node grouping management
### Multi-Language Support
The plugin interface supports 9 languages, automatically detecting the system language:
- English
- Simplified Chinese
- Traditional Chinese
- Japanese
- Russian
- French
- Portuguese
- Spanish
- German
## 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 your Godot project's `addons` directory:
```
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 MCP Server
After enabling the plugin, you'll see the **GodotMCP** panel on the right side of the editor:
- **Server** - Displays server running status, endpoint address, and author information
- **Tools** - Manage available MCP tools (displayed by category)
- **Configuration** - IDE one-click configuration and CLI command copy
Default configuration:
- Port: `3000`
- Address: `http://127.0.0.1:3000/mcp`
- Auto-start: Enabled
### 2. Configure AI Client
#### IDE Editors - One-Click Configuration
In the GodotMCP panel, switch to the 'Configuration' tab to see 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 scope:
- **User-level** - Globally effective, all projects can use
- **Project-level** - Only effective for the current project
2. Copy the corresponding tool's command to execute 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 operate the Godot project in the AI client:
```
User: Help me create a new scene and add a Sprite2D node
AI: Okay, I'll create a scene for you...
[Call scene_create to create a scene]
[Call node_add to add a Sprite2D node]
Done! A new scene with a Sprite2D node has been created.
```
## Tool List
### Core Tools
#### Scene Tools (Scene)
| Tool Name | Description |
|--------|------|
| `scene_create` | Create a new scene |
| `scene_open` | Open a 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 |
#### File System Tools (Filesystem)
| Tool Name | Description |
|--------|------|
| `filesystem_list` | List directory contents |
| `filesystem_read` | Read a file |
| `filesystem_write` | Write 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 a specified node |
| `editor_undo_redo` | Undo/Redo operations |
#### 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` | Manage shader parameters |
#### Lighting Tools (Lighting)
| Tool Name | Description |
|--------|------|
| `lighting` | Configure scene lighting |
#### Particle Tools (Particle)
| Tool Name | Description |
|--------|------|
| `particle` | Create particle effects |
### 2D Tools
#### TileMap Tools (TileMap)
| Tool Name | Description |
|--------|------|
| `tilemap` | TileMap editing |
#### Geometry Tools (Geometry)
| Tool Name | Description |
|--------|------|
| `geometry` | 2D geometric figures |
### 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 |
## Frequently Asked Questions
### Q: The server cannot start?
A: Check if the port is occupied, try changing the port and restarting.
### Q: The AI client cannot connect?
A:
1. Ensure the MCP server is running (status shows green)
2. Check if the port number in the configuration file is correct
3. Restart the AI client
### Q: What to do after changing the port?
A: You need to update the port number in the AI client's configuration file and restart the client.
### Q: How to switch the interface language?
A: In the 'Server' tab's settings area, use the 'Language' dropdown to select your needed language.
## 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 use
### Prohibited:
- Commercial use (including but not limited to sales, integration into commercial products)
- Unauthorized redistribution
Contact the author for commercial use authorization.
## Author
**LIDAXIAN**
- GitHub: [https://github.com/DaxianLee/godot-mcp](https://github.com/DaxianLee/godot-mcp)
- WeChat: `lidaxian-AI`
## Contribution
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
## Acknowledgements
- [Godot Engine](https://godotengine.org/) - Open-source game engine
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI interaction protocol specification
---
If this project helps you, give it a Star!
