# Getting started

Connect Godot MCP to the cloud, wire up an AI agent such as Claude Code, check the connection and run your first AI prompts in the Godot editor.

_Last updated: 2026-11-04_

This page takes you from an installed addon to an AI agent that edits your Godot scene. It assumes the addon is already in your project; if not, start with [Installation](https://ai-game.dev/docs/wiki/godot/installation). The steps use the default Cloud mode, where the editor and your agent both connect to [ai-game.dev](https://ai-game.dev) and you sign in once.

## Step 1: open the project

Open the project with the CLI:

```bash
godot-cli open ./MyGodotProject
```

`open` builds the C# assembly first and then starts the editor. The build matters on the very first open: Godot loads enabled addons immediately, and without a built assembly it reports that it cannot load `GodotMcpPlugin.cs` and disables the addon. If you open the project from the Godot project manager instead, build it once (the editor's Build button or `godot-cli build`) and re-enable the plugin if Godot turned it off.

When the addon loads, the editor's Output panel prints `[Godot-MCP] plugin loaded` and the **AI Game Developer** dock appears in the upper-right dock area.

## Step 2: sign in

Cloud mode needs your ai-game.dev account. Pick one of these:

- In the dock, keep the mode on **Cloud** and click **Authorize**. Your browser opens with a short code; approve it with your ai-game.dev account.
- From a terminal, run `godot-cli login`. It uses the same OAuth device flow and saves the credential to `~/.ai-game-dev/credentials.json`, which the editor picks up by itself.

You sign in once per machine. The same credential serves Godot MCP, Unity MCP, Unreal MCP, the engine CLIs and the AI Game Dev app. The session shows up in your account's connected devices, where you can revoke it. Details: [Authentication](https://ai-game.dev/docs/auth).

## Step 3: connect your AI agent

Write the MCP config for the agent you use. For Claude Code:

```bash
godot-cli setup-mcp claude-code ./MyGodotProject
```

This writes `.mcp.json` in the project with a URL pinned to this project, so the agent reaches this editor even when you have several editors open. You can do the same from the dock: choose your agent in the **AI agent** section and click **Configure**. Other agents (Cursor, VS Code Copilot, Codex, Gemini and more) are listed on [Connecting AI clients](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients).

Restart the agent, or reload its MCP servers, after the config is written. Start the agent from the project folder when the config lives there (Claude Code reads `.mcp.json` from the folder it starts in).

## Step 4: check the connection

The **Connection** section of the dock shows a line of three points: Godot, the MCP server and the AI agent. When the editor is connected and an agent session is active, all three are lit and the agent row names the client. From a terminal you can also wait for the editor to answer:

```bash
godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject
```

`wait-for-ready` polls the readiness probe (`ping`) until it answers, by default for up to two minutes. `status` reports whether an editor is running for the project and whether the server answers.

In your agent, ask it to list its tools, or run `/mcp` in Claude Code. You should see tools such as `rql-query`, `rql-mutate`, `script-create` and `screenshot-viewport`.

## Step 5: first prompts

Try these in your agent's chat. Each one maps to real tools, so you can watch the scene change in the editor:

- "Add a Node3D scene with a Camera3D and a MeshInstance3D cube, then save it as Main.tscn."
- "Create 3 cubes in a circle with radius 2."
- "List every OmniLight3D in the scene with its energy."
- "Create a StandardMaterial3D for the floor and set its albedo color to grey."
- "Create a Player.cs script with a public float Speed, attach it to the Player node and build the project."
- "Add an input action called jump on the Space key."
- "Take a screenshot of the viewport and tell me what you see."

Scene edits made by the agent are undoable: press Ctrl+Z in the editor to step back, exactly like your own edits. Scene changes mark the scene as unsaved, so ask the agent to save, or save yourself. More prompt ideas are on [Best practices for Godot](https://ai-game.dev/docs/best-practices/godot).

## What the agent can and cannot see

The agent works through the tools the addon exposes. It can read the scene tree, Godot properties (including GDScript variables), resources, files, project settings, the input map, autoloads, the console and editor state through RQL, and it can look at screenshots. It cannot click in the editor UI. The full list is on [Tools](https://ai-game.dev/docs/wiki/godot/tools) and in the [Godot tools catalog](https://ai-game.dev/docs/tools/godot).

## Prefer to stay offline?

You can run the MCP server on your own machine instead of using the cloud. In the dock, switch the mode to **Custom** and click **Start Server**: the addon downloads the matching server build from GitHub, starts it and connects to it. Then point your agent at the local URL. See [Connecting AI clients](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients#custom-mode).

## Next steps

- [Configuration](https://ai-game.dev/docs/wiki/godot/configuration): the dock, log level, which tools the agent sees.
- [Extensions](https://ai-game.dev/docs/wiki/godot/extensions): add AnimationPlayer, CSG, navigation, tilemap and addon support.
- [Troubleshooting](https://ai-game.dev/docs/wiki/godot/troubleshooting): if a step above did not work.

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/getting-started