Content
# Godot MCP Server
A Model Context Protocol (MCP) server that allows AI models like Gemini and Claude to interact with Godot Engine projects.
## Features
- **Project Insights**: Read `project.godot` configuration.
- **Scene Inspection**: Parse `.tscn` files to understand node hierarchies.
- **Script Access**: Read and analyze `.gd` (GDScript) files.
- **Asset Management**: List and locate assets within the `res://` directory.
## Setup
### Prerequisites
- [pnpm](https://pnpm.io/) installed.
- Node.js (v18 or higher).
### Installation
1. Clone this repository.
2. Install dependencies:
```bash
pnpm install
```
3. Build the server:
```bash
pnpm build
```
## Usage
### Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/path/to/godot-mcp/packages/server/dist/index.js"],
"env": {
"GODOT_PROJECT_PATH": "/path/to/your/godot/project"
}
}
}
}
```
### Environment Variables
- `GODOT_PROJECT_PATH`: The absolute path to your Godot project root OR a workspace folder containing multiple Godot projects.
## Workspace Mode
If you point `GODOT_PROJECT_PATH` to a folder containing multiple Godot projects, the server enters **Workspace Mode**.
1. The AI can use `list_projects` to discover all games in the workspace.
2. The AI can target specific projects by providing a relative path (e.g., `get_project_info(projectPath: "my-rpg")`).
3. Security is maintained by jailing all operations within the workspace root.
## Tools
### Inspection
- `list_projects`: Finds all Godot projects within the workspace (scans for `project.godot`).
- `get_project_info`: Returns basic information about a Godot project.
- `list_res_files`: Recursively lists all files in the `res://` directory.
- `inspect_scene`: Parses a scene file (.tscn) and returns its node structure.
- `read_script`: Returns the content of a GDScript file (.gd).
### Creation & Modification
- `create_script`: Creates a new GDScript with a basic template.
- `edit_script`: Overwrites a GDScript with new content.
- `create_character_scene`: Generates a 2D or 3D CharacterBody scene with essential child nodes.
- `add_node_to_scene`: Appends a new node to an existing scene file.
## Development
This project uses a pnpm workspace. All dependencies are pinned to specific versions and must be at least 5 days old (enforced by `pnpm-workspace.yaml`).
