godot

GoPeak is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real Godot projects end-to-end. It provides a curated tool surface (compact profile) with 33 core tools plus dynamic groups, enabling in-context project manipulation, runtime inspection, and debugging within Godot projects. You can launch Godot projects, inspect live scenes and resources, create or modify scenes and scripts, manage signals and animations, and access runtime metrics and diagnostics. With the compact tool surface, you get a balance between capability and token efficiency, with additional tools activated on demand via dynamic tool groups.

To use the server, first install the GoPeak MCP client configuration in your client app or environment. The example configuration in the Quick Start shows how to connect using npx and pass environment variables to point GoPeak at your Godot project. Once connected, you can issue natural-language prompts like listing Godot projects, creating a scene, or running a project and inspecting debug output. The server exposes capabilities across scene/script/resource/runtime/LSP/DAP areas, so you can perform in-context edits, inspect class data, and debug live runtime state. Tools can be auto-activated via the catalog or manually via tool.groups for debugging sessions, and the client will receive notifications when the tool list changes.

Typical workflows include launching the editor, running the project to collect logs, inspecting the live scene graph, editing properties or scripts, and applying fixes based on AI-guided analysis. The setup also supports fine-grained control over tool exposure and token usage by leveraging the GOPEAK_TOOL_PROFILE and related environment variables.

Prerequisites

• Godot 4.x installed
• Node.js 18+ installed
• A MCP-compatible client (Claude Desktop, Cursor, Cline, OpenCode, etc.)

A. Quick start (recommended)

1. Install and run via npx:

npx -y gopeak

2. Connect to the GoPeak MCP server (Godot) by adding the following MCP client config:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gopeak"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

B. Global install (alternative)

npm install -g gopeak
gopeak

C. From source (advanced)

git clone https://github.com/HaD0Yun/godot-mcp.git
cd godot-mcp
npm install
npm run build
node build/index.js

GoPeak also exposes two CLI bin names: gopeak and godot-mcp.

Notes and tips:

• Environment variables: GODOT_PATH should point to your Godot executable or project root as required by your setup. GOPEAK_TOOL_PROFILE selects the exposure mode (compact by default). You can override GOPEAK_TOOL_PROFILE using MCP_TOOL_PROFILE as a fallback alias.
• Tool surface and tokens: compact mode exposes 33 core tools with 22 dynamic groups (78 additional tools). Use tool.catalog to discover tools and tool.groups to activate a specific group, then deactivate groups when done to minimize token usage.
• Page size for tools: tools are paginated to avoid sending all 110+ tools at once. Adjust GOPEAK_TOOLS_PAGE_SIZE if your client needs smaller or larger pages.
• Debug workflow: use Run project, capture debug output, inspect logs, and use runtime inspection tools to modify properties or call methods in real time.
• Compatibility: ensure your Godot project is compatible with Godot 4.x APIs and the tools provided by GoPeak. Some features may require specific editor plugins installed via the Addons section in Godot.