Skip to Content
DocsInstallation

Installation

Prerequisites

This plugin needs uv installed on your machine.

To check if it is installed open Command Prompt (on Windows) or Terminal (on macOS) and run the command

uv --version

If you get a valid output with the version, you’re all set.

Terminal uv version

Otherwise run the below command to install uv:

  • Windows

    Open Terminal / Command Prompt and run:

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  • macOS / Linux

    Open Terminal and run:

    curl -LsSf https://astral.sh/uv/install.sh | sh

Now check once again using the uv --version command to see if it was successfully installed.

For detailing uv installation see the UV Installation Guide :

The are 2 main steps in installing this plugin:

  1. Install in your Godot project
  2. Install in your MCP Client eg. Cursor, Windsurf, VSCode, etc

1. Install in Godot project

This is a normal plugin for Godot. To install it follow these steps:

  1. Close the Godot Editor.

  2. Download the latest version of the plugin (zip file) and extract it. You will get an addons folder and inside that there will be gdai-mcp-plugin-godot folder. Folder after extracting the plugin

  3. Copy the addons/gdai-mcp-plugin-godot/ from the extracted zip to res://addons/ of your Godot project. Project after copying the plugin

  4. Now open the project in Godot editor, goto Project -> Project Settings -> Plugins and enable the GDAI MCP plugin. Enable GDAI MCP plugin

    Note: On macOS, you might get a popup saying Apple could not verify the libgdai-mcp-plugin-godot.template_release.dylib. Follow this guide to resolve this issue: macOS - Apple could not verify “libgdai-mcp-plugin-godot.macos.template_release.dylib”

  5. You should see a GDAI MCP tab in the bottom panel of the Editor. GDAI MCP bottom tab

  6. In the GDAI MCP tab, you can:

    • Start/Stop the MCP server
    • Check for plugin updates
    • Find quick links to the Plugin Website, and Docs.
    • The JSON config which you will need to setup the server in a MCP Client is also shown. Copy the JSON for later use. Command to use in MCP client

  7. Now you can proceed to install the MCP server in your MCP client.

Before exporting your game make sure to follow the steps in the Exporting section.

  • In Godot Editor, click the Editor tab at the top, then Editor Settings, make sure to enable the Auto Reload Scripts on External Change and Auto Reload and Parse Scripts on Save options. If you don’t see this options, make sure to enable Advanced Settings in the top right.

    External Script Changes settings

2. Install in MCP Client

Installation may be slightly different based on which MCP Client you are using. Installation steps for some of the popular MCP Clients is given below:

Use your client’s instructions below for the standard setup. If your client asks for an MCP server URL, follow Open WebUI and other HTTP clients.

Open WebUI and other HTTP clients

Starting with GDAI MCP v0.3.3, you can optionally connect through Streamable HTTP. Use this option for clients such as Open WebUI that connect to an MCP server using a URL. If your current client connection works, you can keep using it.

Connect on the same computer

  1. Open your project in Godot with the GDAI MCP plugin enabled. In the GDAI MCP tab, make sure the server is running.

  2. Open a terminal on the same computer as Godot and run the command below. Replace the example path with the path to gdai_mcp_server.py shown in the GDAI MCP tab.

    uv run "/absolute/path/to/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py" --transport http --port 9090

    This command works on Windows, Linux, and macOS. On Windows, a path might look like C:/Projects/MyGame/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py. Keep the quotes if your path contains spaces.

  3. In your AI client’s MCP settings, add a server with connection type Streamable HTTP and URL http://127.0.0.1:9090/mcp. In Open WebUI, add an External Tool Server in the admin settings and select MCP (Streamable HTTP).

  4. Ask the AI to describe your open Godot project to check the connection.

Keep Godot and the terminal running while you use the connection. To stop the HTTP server, press Ctrl+C in the terminal.

If port 9090 is already in use, change --port 9090 to another port, such as --port 9091. Use the same port in your client’s URL.

Connect Open WebUI in Docker

If Open WebUI runs in Docker, use these settings so it can reach Godot on your computer.

  1. Stop the HTTP server if it is running, then start it with this command on the computer running Godot. Replace the example path with your own.

    uv run "/absolute/path/to/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py" --transport http --host 0.0.0.0 --allowed-host host.docker.internal

  2. In Open WebUI, use MCP (Streamable HTTP) with URL http://host.docker.internal:9090/mcp. On Linux Docker Engine, add --add-host=host.docker.internal:host-gateway to the Open WebUI container’s launch options.

This Docker setup allows connections from other devices on your network. The HTTP server has no built-in sign-in, so use it only on a trusted network.

If the connection fails

  • Check that Godot is open, the GDAI MCP server is running, and the HTTP server’s terminal is still open.
  • Check that the URL ends in /mcp and uses the port from your command.
  • If your client runs in Docker, use the Docker instructions above instead of 127.0.0.1.
  • If the command does not recognize --transport, update the plugin to v0.3.3 or later.
  • If you changed your project’s ports, set the environment variables from your GDAI MCP configuration in the terminal before starting the HTTP server. See Configuration. The --port option changes the HTTP connection’s port, not your project’s ports.

Claude Desktop

For installing in Claude Desktop:

  1. Open Claude Desktop, and goto the Settings. Open Settings in Claude Desktop

  2. Then click on Developer, and then click on Edit Config. Then also close Claude Desktop app. Navigate to Edit Config in Developer settings

  3. If you don’t have any MCP servers setup before, you will see the below JSON file.

    {
  "mcpServers": {}
}

  4. Update the JSON file as follows (What you copied earlier from the GDAI MCP tab in Godot):

    {
  "mcpServers": {
    "godot-mcp": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py"]
    }
  }
}

    You can name godot-mcp to whatever you want like my-awesome-game-godot-mcp.

  5. Now open Claude Desktop, and you should see the MCP server as shown in the screenshot below: MCP Server in Claude Desktop chat

  6. You can now chat and start letting AI automate your Godot workflows.

Claude Code

For installing in Claude Code simply run the command:

claude mcp add gdai-mcp uv run path-shown-in-gdai-mcp-tab

Eg.

claude mcp add gdai-mcp uv run /absolute/path/to/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py

Codex

For installing in Codex simply run the command:

codex mcp add godot-mcp -- uv run path-shown-in-gdai-mcp-tab

Eg.

codex mcp add godot-mcp -- uv run /absolute/path/to/addons/gdai-mcp-plugin-godot/gdai_mcp_server.py

Cursor

  1. Open Cursor, and goto Cursor Settings. Goto Cursor Settings

  2. Then click the MCP tab, and then click Add new global MCP server. Click add new MCP server

  3. Now in the text editor that opens, paste the same JSON config which you got from the GDAI MCP tab in Godot. Cursor MCP server config

  4. You should then see the server in Cursor. MCP Server is installed in Cursor

  5. You can now chat and start letting AI automate your Godot workflows.

Windsurf

  1. Open Windsurf, and goto the Cascade section.

  2. Then click the small Hammer icon (1) and then click the Configure button (2) as shown in the screenshot below: MCP Server setting in Windsurf IDE

  3. Now in the text editor that opens, paste the same JSON config which you got from the GDAI MCP tab in Godot. Windsurf MCP server config

  4. You should then see the server in Windsurf. MCP Server is installed in Windsurf IDE

  5. You can now chat and start letting AI automate your Godot workflows.

VS Code Copilot

  1. Open your project in VS Code

  2. Create a folder .vscode if it doesnt exist at the project root.

  3. Create a file mcp.json inside the .vscode folder. VS Code create mcp json

  4. In the mcp.json file paste the same JSON config which you got from the GDAI MCP tab in Godot. Make sure to replace the word mcpServers with just servers. See the below image. VS Code mcp.json view

  5. Restart VSCode, and you should see the GDAI MCP server, in the MCP servers list by clicking the wrench icon in the bottom chat area. VS Code see GDAI MCP server

  6. You can now chat and start letting AI automate your Godot workflows.

Antigravity

  1. Open your project in Antigravity.

  2. Then click the 3 dots button next to the close sidebar button, and then click MCP Servers. Antigravity click more menu

  3. Then click Manage MCP Servers button. Antigravity click manage MCP servers

  4. Then click View raw config button. Antigravity click view raw config

  5. Then paste the same JSON config which you got from the GDAI MCP tab in Godot.

    Antigravity MCP server config

Antigravity Windows Fix

If you’re on Windows, the mcp server will not directly work on Antigravity due to stricter rules. As a workaround, in the MCP server JSON config replace the gdai_mcp_server.py with antigravity_windows_fix.py

Antigravity MCP server config windows fix

Installation instructions not found for my IDE / MCP client

If the MCP server installation instructions are not mentioned for your IDE or MCP client, please contact 3ddelano in the Discord server .

3. Try it out

Once you have installed both in Godot and in your MCP client. Make sure that your project is open in the Godot Editor. Then you start chatting about your project and ask the AI to work on the project.

Next steps:

Last updated on
IntroductionCommon Issues