GoPeak

🌐 Languages: English | 한국어 | 日本語 | Deutsch | Português | 简体中文

GoPeak is an MCP server for Godot 4 that gives AI assistants a real edit → run → inspect → fix loop.

It is designed for trusted Godot 4 workflows: small default tool surface, setup-gated advanced capabilities, and explicit compatibility rules for older/legacy tool names.

English is the canonical source of truth. Localized READMEs are concise overviews and may lag behind README.md.

Discord is temporarily unavailable while the invite link is refreshed. Use GitHub Discussions for now.

Quick Start

Requirements

• Godot 4.x
• Node.js 18+
• MCP-compatible client such as Claude Desktop, Cursor, Cline, or OpenCode

1) Run GoPeak

bashCopy code
npx -y gopeak

or install globally:

bashCopy code
npm install -g gopeak
gopeak

2) Add MCP client config

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

compact is the default profile. It keeps the initial MCP context small and exposes additional setup-gated groups only when requested.

3) Try these prompts

• "List Godot projects in /your/projects and show project info."
• "Create scenes/Player.tscn with a CharacterBody2D root and a movement script."
• "Run the project, read the debug output, and fix the top error."
• "Use tool.catalog to find animation tools, then activate the right group."

What You Get

Setup gates

Some capabilities require extra Godot-side services. GoPeak labels these instead of pretending everything is always available:

Add the Godot Plugins

Install from your Godot project folder:

bashCopy code
curl -sL https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.sh | bash

PowerShell:

powershellCopy code
iwr https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex

Then enable plugins in Project Settings → Plugins:

• godot_mcp_editor for bridge-backed scene/resource tools
• godot_mcp_runtime for runtime inspection, screenshots, and input workflows

Optional shell hooks for update notifications are opt-in:

bashCopy code
gopeak setup

gopeak setup only modifies supported bash/zsh rc files when you run it explicitly. npm install does not install shell hooks automatically.

Tool Profiles

GoPeak supports three exposure profiles:

Set either GOPEAK_TOOL_PROFILE or the fallback alias MCP_TOOL_PROFILE.

Dynamic groups

In compact mode, search with tool.catalog; matching groups auto-activate. You can also manage groups directly with tool.groups.

Common groups:

If your MCP client does not refresh after activation, reconnect the client or call the newly activated tool once to force a fresh tools/list round-trip.

GoPeak also uses cursor-based pagination for tools/list so large profiles are not dumped into context at once. Tune it with GOPEAK_TOOLS_PAGE_SIZE when needed.

Typed Godot Values

Bridge-backed scene tools such as add_node and set_node_properties accept common vector payloads for typed properties:

jsonCopy code
{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

Plain { "x": 100, "y": 200 } and [100, 200] are also coerced for common Vector2 fields, but tagged values are safest across tools.

Useful Commands

bashCopy code
# run from npm
npx -y gopeak

# install globally
npm install -g gopeak

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

# local verification
npm run ci
npm run test:dynamic-groups
npm run test:metadata
npm run test:packaging

CLI bin names:

• gopeak
• godot-mcp

Environment & Ports

Runtime screenshot tools (capture_screenshot, capture_viewport) use a GoPeak-managed temporary PNG file when the runtime addon supports output_path, then return normal MCP image content. Older runtime addons that do not receive an output_path continue to return inline base64 screenshots.

Troubleshooting

• Godot not found → set GODOT_PATH.
• No MCP tools visible → restart your MCP client.
• Need a hidden tool → search with tool.catalog or activate a group with tool.groups.
• Project path invalid → confirm project.godot exists.
• Runtime tools not working → install/enable the runtime addon and check port 7777.
• Runtime screenshots time out → update the runtime addon so screenshot commands support the managed output_path flow. For slow runtime responses, raise GOPEAK_RUNTIME_TIMEOUT_MS; older addons may still time out on large inline base64 screenshots.
• Editor bridge disconnected → stop duplicate gopeak/MCP servers that may already own bridge port 6505; get_editor_status reports bridge startup errors such as EADDRINUSE.

Migration & Deprecation Policy

GoPeak treats compact as the safe default and full/legacy as compatibility profiles. Future hide, remove, rename, or API-contract changes must include:

1. old → new mapping or an explicit no-replacement note;
2. profile impact (compact, full, legacy, or opt-in group);
3. alias window and planned removal timing;
4. README/docs and release-note updates;
5. verification proving tools/list exposure and alias behavior;
6. migration prompt examples for common Godot workflows.

Current stance: legacy tool names and compact aliases remain supported. Optional external groups (runtime, testing, lsp, dap, asset_store) are setup-gated, not always-available core behavior.

Full policy: docs/migration-policy.md.

More Docs

• Documentation Map
• Architecture
• Migration Policy
• Release Process
• CHANGELOG
• ROADMAP
• CONTRIBUTING

License & Credits

MIT — see LICENSE.

• Original MCP server by Coding-Solo
• GoPeak enhancements by HaD0Yun
• Project visualizer inspired by tomyud1/godot-mcp