Funplay MCP for Godot

The Most Advanced MCP Server for Godot Editor

Godot Asset Store · 中文 | English

💖 If you find this project useful, please consider giving it a Star. It helps more Godot developers discover it and supports ongoing development.

Funplay MCP for Godot is an MIT-licensed Godot Editor MCP server that lets AI assistants like Claude Code, Cursor, Windsurf, Codex, and VS Code Copilot operate directly inside your running Godot project.

The addon works in standard Godot 4.2+ projects and is also usable in Godot .NET projects. The current implementation is GDScript-based, and the exported script tools are language-aware: GDScript projects see GDScript workflows, .NET projects see C#/.NET workflows, and mixed projects expose both where useful.

Describe your game or tool in one sentence — your AI assistant builds it in Godot through Funplay MCP for Godot’s built-in tools for scene creation, script generation, UI authoring, play-mode validation, input simulation, animation setup, camera control, performance inspection, and editor automation.

"Build a top-down shooter HUD with health, ammo, pause menu, and hit flash feedback"

Your AI assistant handles it through Funplay MCP for Godot: creates the scene structure, generates scripts, builds the Control tree, wires signals, configures animations, and validates the workflow — all from a single prompt.

Quick Start

If you just want to get connected fast, do these three things:

• Open the project or copy addons/funplay_mcp into your own Godot project
• Enable the plugin and start the MCP server
• Use the built-in one-click client configuration

1. Install the addon

You can either:

• install it from the Godot Asset Store,
• download Funplay.GodotMcp.vX.Y.Z.zip from the latest GitHub Release and extract it into your project root,
• clone this repository and open it directly as a Godot project, or
• copy addons/funplay_mcp into your own Godot res://addons/ directory

💡 Before you clone or install, a quick ⭐ on GitHub would be greatly appreciated.

2. Enable and start the MCP Server

In Godot:

• open Project → Project Settings → Plugins
• enable Funplay MCP for Godot
• use the Funplay MCP dock on the right side

The server starts on http://127.0.0.1:8765/ by default. If that port is already occupied, it automatically picks another free local port and saves it to user://funplay_mcp_settings.cfg. Local MCP POST requests require the per-project auth token stored in user://funplay_mcp_settings.cfg; the dock writes it into generated stdio client configs automatically. Authenticated clients can run high-impact editor tools, including execute_code; keep the server enabled only while working with trusted local clients and leave safety checks on unless you intentionally need to override them. The dock also shows the installed addon version and includes a Check Updates action that opens the latest GitHub Release when a newer version is available. Use the Language selector at the top of the dock to switch between English and Simplified Chinese. The choice is saved in user://funplay_mcp_settings.cfg and restored the next time the project opens.

3. Configure Your AI Client

Use the built-in One-Click MCP Configuration in the Funplay MCP dock first.

Select your target client, click Configure, and the addon writes the recommended MCP config entry for you. Use Configure + Skills when you also want the addon to generate project-local skill files under res://.funplay/skills/ and an AGENTS.md bridge for AI clients that read repository instructions.

If Godot had to pick a different port, use the endpoint shown in the dock. If you prefer to edit config files manually, use the examples below as fallback references:

{
  "mcpServers": {
    "funplay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "funplay-godot-mcp@0.10.0"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

{
  "mcpServers": {
    "funplay": {
      "command": "npx",
      "args": ["-y", "funplay-godot-mcp@0.10.0"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

{
  "servers": {
    "funplay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "funplay-godot-mcp@0.10.0"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

[mcp_servers.funplay]
url = "http://127.0.0.1:8765/"

Optional stdio wrapper

Most clients can connect directly to the addon over HTTP. For clients or registries that prefer stdio packages, this repository also includes an npm-ready wrapper under stdio-wrapper/.

cd stdio-wrapper
npm link
FUNPLAY_GODOT_MCP_URL=http://127.0.0.1:8765/ funplay-godot-mcp

After the wrapper is published to npm, replace npm link with npm install -g funplay-godot-mcp.

Example MCP client entry:

{
  "mcpServers": {
    "funplay": {
      "command": "funplay-godot-mcp",
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/"
      }
    }
  }
}

4. Verify the Connection

Open your AI client and try a few safe requests first:

• "Call get_scene_info and tell me what scene is open."
• "Read godot://project/context and summarize the current editor state."
• "Use execute_code to return the active scene name."

If those work, the MCP server, resources, and primary execution tool are connected correctly.

5. Start Building

Open your AI client and try: "Create a 2D HUD with health bar, score label, and pause button"

Before You Start

• This addon is Editor-only. It does not add runtime components to your exported game.
• The MCP server starts on http://127.0.0.1:8765/ by default. If the same project already owns that port, the dock attaches to it; otherwise it falls back to another free local port.
• Local MCP server settings are stored in user://funplay_mcp_settings.cfg.
• The language selector localizes the Dock UI only; MCP tool names, protocol fields, and generated client configuration identifiers remain stable in English for compatibility.
• The addon defaults to the core MCP tool profile to reduce tool-list noise for AI clients. Switch to full in the dock if you want the complete tool surface.
• The dock includes a Tool Exposure panel for disabling individual tools within the active profile, plus optional debug logging and execute_code safety toggles.
• execute_code safety checks are on by default for common process, filesystem, and project-setting mutations. A reviewed call can pass safety_checks=false.
• Play-mode requests are deferred until after the MCP response is sent and repeated calls are idempotent. Projects configured for more than one run instance must pass allow_multiple_instances=true; use restart_if_running=true only for an intentional restart, then inspect get_play_state for the confirmed transition.
• The dock can check GitHub Releases for newer addon versions and surface whether release zip, manifest, SHA256, and server.json artifacts are present.
• Focused MCP tools run directly. There is no extra approval toggle inside the addon.
• The built-in dock can copy or write recommended MCP config entries for Codex, Claude Code, Cursor, and VS Code.

Why This Project