# Godot MCP Server

`godot-mcp` lets MCP clients inspect, validate, test, export, and query Godot projects. It supports headless Godot commands and, optionally, live state from an open Godot editor.

## Requirements

- Node.js 18 or newer
- Godot 4.1 or newer, installed locally
- A Godot project containing `project.godot`

The live-editor tools additionally require the MCP Bridge addon described below. The remaining tools run headlessly.

## Install

### From a local checkout

```bash
npm install
npm run build
```

### From npm (after publication)

```bash
npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot
```

## Configure an MCP client

Always provide the project path. MCP desktop clients usually start servers in their own working directory, so automatic project discovery alone is not reliable.

```json
{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}
```

The equivalent command-line options are:

```bash
godot-mcp --project /path/to/godot-project --godot /path/to/godot
```

`GODOT_PATH`/`--godot` is optional only when the `godot` executable is already on `PATH`. On Windows, a `_console.exe` executable is preferred.

## Enable live editor tools

1. Copy [`godot-plugin/addons/mcp_bridge`](godot-plugin/addons/mcp_bridge) to `<your-project>/addons/mcp_bridge`.
2. In Godot, open **Project > Project Settings > Plugins** and enable **MCP Bridge**.
3. Keep the Godot editor open while using live tools.

The bridge listens on `127.0.0.1:7000` by default. Set `mcp/plugin/port` in `project.godot` to override it; the server reads that setting from the project configured above. Exclude `addons/mcp_bridge/*` from production export presets.

## Tools

- Project and export: `get_project_settings`, `list_export_presets`, `export_project`
- Tests and validation: `run_tests`, `validate_scene`, `validate_script`, `run_scene`, `format_gdscript`
- Scenes and resources: `inspect_scene_tree`, `find_nodes`, `get_node_properties`, `get_node_connections`, `list_resources`, `get_resource_dependencies`, `resolve_path`, `get_resource_info`
- Documentation: `verify_api`, `get_help`
- Live editor: `get_editor_selection`, `get_open_scenes`

Most tools return a structured JSON result with `success`, `data`, `errors`, `warnings`, and timing metadata.

## Development and verification

```bash
npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published
```

GitHub Actions runs both the Node/MCP tests and Godot-addon checks on pushes and pull requests.

## Release checklist

1. Update the version in `package.json`.
2. Run `npm test`, `npm run test:godot`, and `npm pack --dry-run`.
3. Publish with `npm publish` and create a matching GitHub release.

## License

This project is licensed under the [MIT License](LICENSE).