Gopeak

Made with Godot Bun GitHub Release

🌐 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
• Bun 1.3.3+
• MCP-compatible client such as Claude Desktop, Cursor, Cline, or OpenCode

1) Install GoPeak

bun add -g https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz

That is the quickest installation path. It installs the bundled runtime directly from GitHub Releases without npm. For a checksum-verified installation, use:

curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz
curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c gopeak-2.3.9.tgz.sha256
else
  shasum -a 256 -c gopeak-2.3.9.tgz.sha256
fi
bun add -g "$PWD/gopeak-2.3.9.tgz"

The verified path checks the downloaded release before Bun installs it globally. The absolute tarball path avoids a relative-path bug in Bun 1.3.3. The checksum command works on Linux (sha256sum) and macOS (shasum). To use the supported installer instead, download or clone the repository and run it locally—do not pipe a remote script into a shell:

git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
./install.sh

The release archive contains the bundled runtime. Installation and execution do not contact the npm registry or require npm credentials. For stronger provenance checking, release reviewers can also verify the GitHub artifact attestation as described in the release process.

If you used the old installer, --dir, --godot, and --configure remain accepted with warnings through the 2.3.x line and are planned for removal in 3.0.0. The new mappings are: use Bun's global home (BUN_INSTALL) instead of a source checkout directory, put GODOT_PATH in the MCP client env, and use the configuration below instead of relying on installer output. During the compatibility window, --godot and --configure still print a client snippet but never write client files. See the migration policy for the exact contract.

2) Add MCP client config

{
  "mcpServers": {
    "godot": {
      "command": "gopeak",
      "args": [],
      "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

Workflow	What GoPeak can do
Project control	Find projects, launch the editor, run/stop the game, collect debug output.
Scene + script editing	Create scenes, add nodes, edit typed properties, create/modify GDScript.
Resource workflows	Work with resources, materials, shaders, imports, and export-related checks.
Debugging	Use logs, Godot LSP diagnostics, DAP breakpoints/stack traces, and runtime inspection when configured.
Runtime testing	Capture screenshots, inspect live trees, inject input, and call runtime methods through the addon.
Tool discovery	Keep the default surface compact, then activate capability groups with tool.catalog or tool.groups.

Setup gates

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

Capability	Requires
Editor bridge scene/resource edits	godot_mcp_editor plugin enabled in the Godot project.
Runtime inspection, screenshots, input injection	Runtime addon/socket, default port 7777.
GDScript LSP tools	Godot LSP enabled on port 6005.
DAP debugging tools	Godot DAP enabled on port 6006.
Asset store/provider tools	Network access and provider availability.

---

Add the Godot Plugins

Install from your Godot project folder:

curl -sL https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.sh | bash

PowerShell:

iwr https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/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:

gopeak setup

gopeak setup only modifies supported bash/zsh rc files when you run it explicitly. Installing the release asset does not add shell hooks automatically.

---

Tool Profiles

GoPeak supports three exposure profiles:

Profile	Use when
compact	Default. Trusted core tools plus dynamic groups activated on demand.
full	Compatibility/audit mode for the full legacy surface.
legacy	Older config alias with the same exposed behavior as full.

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:

Group	Status	Notes
runtime	optional-runtime	Live scene tree, properties, method calls, metrics. Requires runtime addon/socket.
testing	optional-runtime	Screenshots, viewport capture, input injection. Requires runtime/editor setup.
lsp	optional-lsp	Diagnostics, completion, hover, symbols. Requires Godot LSP on port 6005.
dap	optional-dap	Breakpoints, stepping, stack traces. Requires Godot DAP on port 6006.
asset_store	optional-network	External CC0 asset search/download. Network/provider dependent.
class_advanced	trusted-static	ClassDB/inheritance discovery backed by static engine metadata.
tilemap	audit-required	Must account for Godot 4.3+ TileMapLayer behavior before promotion.
mutation groups	audit-required	Scene/resource/script/settings/signal/autoload/import/audio/navigation/theme/animation groups need fixture evidence before being marketed as fully trusted.
intent_tracking	workflow-layer	Workflow memory/handoff helpers, not a Godot engine primitive. Keep opt-in.

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:

{
  "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

# run the globally installed CLI
gopeak

# run from source
git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
bun ci
bun run build
bun run ./build/index.js

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

CLI bin names:

• gopeak
• godot-mcp

---

Environment & Ports

Name	Purpose	Default
GOPEAK_TOOL_PROFILE	Tool exposure profile: compact, full, legacy	compact
MCP_TOOL_PROFILE	Fallback profile env alias	compact
GODOT_PATH	Explicit Godot executable path	auto-detect
GODOT_BRIDGE_PORT	Bridge/Visualizer HTTP+WS port override	6505
GOPEAK_BRIDGE_HOST	Bridge/Visualizer bind host	127.0.0.1
GOPEAK_TOOLS_PAGE_SIZE	Number of tools per tools/list page	33
GOPEAK_RUNTIME_TIMEOUT_MS	Runtime addon command timeout in milliseconds	10000
DEBUG	Enable server debug logs	false
LOG_MODE	Recording mode: lite or full	lite

Port	Service
6505	Unified Godot Bridge + Visualizer server on loopback by default.
6005	Godot LSP.
6006	Godot DAP.
7777	Runtime addon command socket.

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