How to Use Godot AI MCP with Cursor - First Safe Editor Session 2026

If you are searching godot ai mcp, you do not need another “AI builds my game from vibes” thread. You need a Monday path: install the hi-godot/godot-ai plugin into a throwaway Godot project, start the local MCP server, connect Cursor (or Claude Code), run a read-only smoke, then decide keep or hold before any write tool touches a scene you care about.

Why this matters now: On July 24, 2026, godot-ai v3.0.6 shipped on GitHub while the repo sat near ~1,200 stars—a production-grade MCP bridge that connects agents to a live Godot editor (not a paste-error-text loop). The plugin is also listed on the Godot Asset Library and the newer Godot Asset Store path. That lands in the same tooling wave as Unity MCP, Unreal MCP, and Phaser Game Agent MCP—except this evening is Godot-native: AssetLib install, uv for the Python server, WebSocket bridge into EditorInterface, and a dock that can auto-configure Cursor.

Who this is for: creators who already pay for Cursor/Claude and want Godot hierarchy reads tonight; Godot 4.5+ indies evaluating editor agents without copying a Unity MCP checklist; studio leads who need allowlist, telemetry, and LAN honesty before anyone enables write ops on a shared branch.
Time: about 60–90 minutes for first safe session + 10 minutes to file the receipt.
Honest limit: Godot AI MCP can create nodes, edit scripts, and run tests through ~43 tools / 120+ ops. It is not a Steam Pipe substitute, not an excuse to skip git, and not permission to open --allow-host on a coffee-shop Wi‑Fi.

Non-repetition: This is not the Unity MCP Cursor bridge (Unity Editor + Unity Cloud AI subscription). It is not the Phaser Game Agent MCP evening (cloud play URL + billed build minutes). It is not the GameMaker GM-CLI + Claude Code terminal evening (CLI compile/run, not a live Godot dock). It is not the old Godot + AI top-down weekend prototype challenge (generic AI assistance, no MCP plugin). Same allowlist discipline family—different engine and install surface.

Why Godot AI MCP is trending for indies

1. MCP is where Cursor users already live. After Unity and Phaser shipped agent bridges, Godot creators asked for the same pattern: real tools against a live editor, not hallucinated scene trees. Godot AI answers that with HTTP MCP at http://127.0.0.1:8000/mcp and a WebSocket bridge into the editor (README architecture).
2. AssetLib makes the first evening possible. One-click Godot AI from AssetLib (plus uv) lowers the barrier versus hunting obscure forks. AssetLib can lag GitHub—prefer the latest release ZIP when you need v3.x fixes the same week they land.
3. SERP is install-heavy. Vendor READMEs and competing “Godot MCP setup” posts explain clone/configure. They rarely ship an indie G1–G6 keep/hold, a secrets/telemetry table, LAN risk language, and explicit non-overlap vs Unity/Phaser/GM evenings already on this site. That gap is what this URL closes.

Parent demand under Godot stays enormous: Semrush-class snapshots put godotengine.org around ~3.19M visits in June 2026. Godot AI MCP how-to intent rides that audience when creators search after seeing Unity MCP screenshots in Discord.

For engine contribution policy (different topic—do not confuse MCP gameplay tooling with engine PR rules), see Stop Shipping AI-Authored Godot Engine PRs - 2026 Contribution Policy.

What Godot AI MCP is (and is not)

Official framing from the maintainers: connect MCP clients to a live Godot editor so assistants can build scenes, edit nodes and scripts, wire signals, and configure UI—via the Model Context Protocol, not via copy-paste alone.

Who this session is for

Who should skip tonight: anyone still on Godot older than 4.5, anyone without uv and unwilling to install it, anyone about to point write tools at a shared main branch with no backup, and anyone who thinks MCP replaces playtesting.

Prerequisites checklist

Confirm every line before you enable the plugin on a project you ship.

• [ ] Godot 4.5+ installed (4.7+ recommended per godot-ai README).
• [ ] uv on PATH (Python server dependency).
• [ ] An MCP client you control—Cursor, Claude Code, Claude Desktop, Codex, or another client listed in the dock.
• [ ] A throwaway Godot project (or a dedicated branch)—not the shared production tree.
• [ ] Named session owner who files the verification receipt at the end.
• [ ] Written keep/hold rule: no write tools until G3 (read smoke) passes.

Windows PowerShell install for uv (from Astral’s docs, also linked in the plugin README):

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

macOS / Linux:

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

Then open a new terminal and confirm uv --version prints something sane before you blame the plugin.

Beginner path - first safe Godot AI MCP evening

This is the shortest path to “it works” for someone who has never configured MCP. Developers can skim to the G1–G6 table, but do not skip the read-only smoke.

Step 1 - Create a throwaway project

1. Open Godot → New Project.
2. Name it something obvious (mcp-smoke-2026).
3. Use a 2D or 3D template—does not matter for hierarchy smoke.
4. Confirm the project path is not inside your Steam demo repo.

Step 2 - Install the plugin (pick one)

Option A — GitHub release ZIP (recommended when you want today’s fixes)

1. Download the latest godot-ai-plugin.zip (v3.0.6+ as of this article’s research window).
2. Extract so you get addons/godot_ai inside your project.
3. Reopen the project in Godot so it rescans addons.

Option B — Clone into addons

git clone https://github.com/hi-godot/godot-ai.git
cp -r godot-ai/plugin/addons/godot_ai your-project/addons/

Option C — AssetLib

1. In Godot, open the AssetLib tab.
2. Search Godot AI.
3. Download → Install.
4. If the dock misbehaves, disable and re-enable the plugin under Project → Project Settings → Plugins (README callout).

Step 3 - Enable Godot AI and watch the dock

1. Project → Project Settings → Plugins → enable Godot AI.
2. Open the Godot AI dock.
3. Confirm status shows the MCP server starting / connected (not a permanent red failure).
4. Note the server URL: http://127.0.0.1:8000/mcp.

If the dock never becomes healthy, stop here. Fix uv, Python, or plugin enablement before you invent Cursor JSON by hand.

Step 4 - Configure Cursor from the dock

1. In the Godot AI dock, open Clients & Tools (or the Clients list).
2. Find Cursor.
3. Click Configure (or Configure all if you intentionally want every client).
4. Restart Cursor if the dock instructs you to.

Prefer dock auto-configure on night one. Manual JSON is a fallback when the client is missing from the list—not a badge of honor.

Step 5 - Read-only smoke (beginner verification)

In Cursor, with the throwaway project open as the workspace:

1. Ask: “Show me the current scene hierarchy.”
2. Confirm the answer matches what you see in Godot’s Scene dock.
3. Confirm nothing in the scene changed (no new nodes, no renames).

Pass: accurate hierarchy, zero mutations. Fail: invented nodes, empty answers while the dock says disconnected, or any unexpected scene edit—stop and re-check plugin + Cursor MCP entry before write tools.

Optional second read: “Search the project for PackedScene files.” Still read-only intent—verify the FileSystem dock matches the answer.

Developer path - G1–G6 keep/hold gates

Treat these as a single evening script. Do not “skip to the cool demo” until G3 is green.

Minute-by-minute script (working-dev)

Allowlist policy - what the agent may touch tonight

Godot AI exposes a wide surface (scenes, scripts, materials, tests). Your first evening should behave like a rented workshop, not an open warehouse.

Approve first (read / inspect)

• Hierarchy / node inspection
• Project searches for scenes and scripts
• Console / error reads when available
• Read-only godot:// resources

Approve second (tiny writes)

• Create a single named node under a known parent
• Rename that same node
• Add an empty script stub only if you asked for it

Hold until a second session

• Bulk scene rebuilds (“make me a voxel game” on night one)
• Mass signal rewires across many scenes
• Anything that touches export presets, CI configs, or Steam credentials files
• --allow-host / LAN binding

Never paste into the agent chat

• Steamworks keys, Discord bot tokens, cloud API secrets
• .env contents, service account JSON
• Partner zip passwords

If your MCP client has per-tool approval, use it. If it only has “always allow,” keep the session short and on a throwaway project until you trust the tool list in docs/TOOLS.md.

Cursor vs Claude Code vs other clients

Server URL stays http://127.0.0.1:8000/mcp unless you deliberately change bind settings—which you should not on night one.

Architecture in one picture (why loopback matters)

MCP Client (Cursor / Claude)
   | HTTP (/mcp)  →  127.0.0.1:8000
   v
Python Server (FastMCP)
   | WebSocket     →  127.0.0.1:9500
   v
Godot Editor Plugin
   | EditorInterface + SceneTree
   v
Your open project

Default bind is loopback. The README’s --allow-host mode is for trusted LAN / remote agents with CIDR gates—and even then, prefer SSH tunnel or Tailscale on untrusted networks. Night-one rule: leave loopback alone.

Telemetry, privacy, and company diligence

Godot AI documents anonymous telemetry (no code, no scene contents, no project or file names). Project-directory slugs are hashed; you can opt out:

export GODOT_AI_DISABLE_TELEMETRY=true
# or
export DISABLE_TELEMETRY=true

For studio policy, treat opt-out as a named decision in the receipt: who approved telemetry on/off, which machines may run MCP, and whether write tools are allowed on shared branches. Pair this with the contribution-policy reality that engine PRs and game project agent edits are different governance problems—see the Godot contribution policy playbook.

Diligence questions a partner might ask

• Is MCP enabled only on developer workstations (loopback), or exposed on a network?
• Which tools are allowlisted in the MCP client?
• Are secrets excluded from agent context by policy?
• Is there a receipt for the first write session on each major branch?

Common mistakes (and fast fixes)

Verification receipt (godot_ai_mcp_first_session_receipt_v1)

File this in your team notes or repo receipts/ folder after the evening. JSON shape for diligence:

{
  "schema": "godot_ai_mcp_first_session_receipt_v1",
  "session_date": "2026-07-24",
  "owner": "named-human",
  "godot_version": "4.x.x",
  "plugin_version": "3.0.6",
  "install_path": "addons/godot_ai",
  "client": "Cursor",
  "server_url": "http://127.0.0.1:8000/mcp",
  "gates": {
    "G1_install": "pass",
    "G2_bridge": "pass",
    "G3_read_smoke": "pass",
    "G4_allowlist": "pass",
    "G5_write_micro": "hold",
    "G6_receipt": "pass"
  },
  "telemetry_opt_out": true,
  "allow_host_used": false,
  "keep_hold": "keep-read-only-until-second-session",
  "notes": "Hierarchy smoke matched Scene dock; write tools still denied."
}

Keep means: dock healthy, G3 green, you will run a second session with one controlled write.
Hold means: reconnect flaky, hallucinated hierarchy, or any unexpected mutation—uninstall/disable until fixed.

Godot AI MCP vs Unity MCP vs Phaser Agent (decision table)

Pick the bridge that matches the engine you ship. Do not paste Unity allowlist JSON into Godot and call it done.

After tonight - what “keep” unlocks next week

If G1–G4 passed and you kept write tools narrow:

1. One script edit session with git commits between prompts.
2. One test_run pass using the plugin’s GDScript test framework docs (see project docs/testing.md upstream)—only after you understand what suites exist under res://tests/.
3. A second machine smoke if another teammate will use Cursor—do not assume one Configure click travels by magic.

If you are evaluating AI tooling across stacks, keep the receipts separate: Godot AI MCP, Unreal 5.8 MCP, and Unity CLI agent sessions are different write surfaces and different blast radii.

Key takeaways

• godot ai mcp in 2026 means hi-godot/godot-ai: live editor tools over MCP, not paste-only chat.
• Prefer GitHub release ZIP when AssetLib lags; still require uv.
• First evening = throwaway project + dock Configure + hierarchy read smoke.
• G1–G6 beat vibes: install, bridge, read, allowlist, tiny write, receipt.
• Default 127.0.0.1:8000/mcp; hold --allow-host until you have a real remote-agent need.
• Opt out of telemetry with GODOT_AI_DISABLE_TELEMETRY when policy requires it.
• Do not mix Godot MCP receipts with Unity MCP, Phaser Agent, or GM-CLI evenings.
• Wide demos (“build a whole game”) are session two, not session one.
• Windows users: watch uv hard-link locks; re-Configure Claude Desktop with UV_LINK_MODE=copy when the dock shows drift.
• Engine contribution policy ≠ game-project MCP edits—govern them separately.

FAQ

What is Godot AI MCP?

Godot AI MCP is the Model Context Protocol bridge shipped by hi-godot/godot-ai. A Godot editor plugin starts a local Python MCP server so clients like Cursor or Claude Code can call real editor tools (scenes, nodes, scripts, tests) against your open project.

How do I install Godot AI for Cursor?

Install addons/godot_ai via GitHub ZIP, clone, or AssetLib; enable the plugin; install uv; use the Godot AI dock to Configure Cursor; restart Cursor; then run a hierarchy read smoke before any write tools.

Does Godot AI MCP require a Unity-style subscription?

No Unity Cloud AI subscription is involved. You need Godot 4.5+, uv, the plugin, and whatever you already pay for your MCP client / LLM. Upstream also documents optional anonymous telemetry you can disable.

Is AssetLib safe for the first install?

Yes for a first evening if the dock becomes healthy. AssetLib can lag GitHub—if you need the same-day v3.x fix, use the latest release ZIP and toggle the plugin.

What should I ask the agent first?

Ask for the current scene hierarchy or a PackedScene search. Confirm the answer matches the editor with zero scene mutations. Only then consider a single named node create under a known parent.

Can I expose Godot AI MCP on my LAN?

Technically yes via --allow-host with CIDR gates, per upstream docs. For a first session, stay on loopback. Prefer SSH tunnels or Tailscale if you later need a remote coding agent.

How is this different from Phaser Game Agent MCP?

Phaser’s MCP path drives a cloud agent that bills build minutes and returns play URLs. Godot AI MCP drives a local Godot editor through tools. Different cost model, different blast radius, different keep/hold.

How is this different from the Godot AI contribution policy article?

That post covers engine repository contribution rules and AI-authored PRs. This post covers editor MCP tooling for your game project. Do not treat them as the same checklist.

Related reading

• Unity MCP with Cursor - First Safe Editor Bridge Session 2026
• How to Use Phaser Game Agent MCP with Cursor - First Browser Game Evening 2026
• Unreal Engine 5.8 MCP with Claude Code - First Safe Editor Session 2026
• How to Use GameMaker GM-CLI with Claude Code - First Terminal Agent Evening 2026
• Stop Shipping AI-Authored Godot Engine PRs - 2026 Contribution Policy
• Godot 4.7 Upgrade Lock - HDR, AreaLight3D, and Asset Store Before Ship 2026
• Godot 4.8-dev2 - VCS Diffs and Play Scene QoL for Indies 2026
• Cursor 3.11 Side Chats for Game Developers - What Changed in 2026

Official and useful sources

• hi-godot/godot-ai on GitHub
• godot-ai v3.0.6 release
• Godot AI on Asset Library
• Model Context Protocol introduction
• uv installation docs