Gopeak

GoPeak

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

GoPeak is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real projects end-to-end.

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

Discord community chat is temporarily unavailable while the invite link is refreshed. Please use GitHub Discussions in the meantime: https://github.com/HaD0Yun/Gopeak-godot-mcp/discussions

---

Quick Start (3 Minutes)

Requirements

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

1) Run GoPeak

npx -y gopeak

or install globally:

npm install -g gopeak

gopeak

Optional shell hooks for update notifications are now opt-in:

gopeak setup

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

2) Add MCP client config

{

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

GOPEAK_TOOL_PROFILE=compact is the default. It exposes a trusted core surface with dynamic tool groups that activate on demand — keeping token usage low while making experimental or environment-dependent capabilities explicit.

3) First prompts to try

• "List Godot projects in /your/projects and show project info."
• "Create scenes/Player.tscn with CharacterBody2D root and add a movement script."
• "Run project, get debug output, then fix top error."

---

Why GoPeak

• Real project feedback loop: run the game, inspect logs, and fix in-context.
• Trusted Godot 4 workflow tools across project discovery, scene/script/resource editing, runtime/LSP/DAP integrations, testing, and asset workflows.
• Token-efficient by default: compact core surface + dynamic tool groups. Activate only the capability family you need instead of loading the full legacy surface.
• Dynamic tool groups with explicit maturity labels: search with tool.catalog and matching groups auto-activate, or manually activate with tool.groups.
• Deep Godot integration with setup gates: ClassDB queries, runtime inspection, debugger hooks, and bridge-based scene/resource edits clearly state addon, editor, LSP, DAP, or runtime requirements.

Best For

• Solo/indie developers moving quickly with AI assistance
• Teams that need AI grounded in actual project/runtime state
• Debug-heavy workflows (breakpoints, stack traces, live runtime checks)

---

Tool Surface Model (Important)

GoPeak supports three exposure profiles:

• compact (default): trusted core tools plus dynamic tool groups activated on demand.
• full: exposes the full legacy tool list for compatibility and audit work.
• legacy: same exposed behavior as full for older configurations.

Configure with either:

• GOPEAK_TOOL_PROFILE
• MCP_TOOL_PROFILE (fallback alias)

Dynamic Tool Groups (compact mode)

In compact mode, additional tools are organized into dynamic groups that activate automatically when needed. Maturity labels are intentionally conservative until each group has Godot 4 fixture evidence:

How it works:

1. Auto-activation via catalog: Search with tool.catalog and matching groups activate automatically.

"Use tool.catalog with query animation and show relevant tools."

1. Manual activation: Directly activate a group with tool.groups.

"Use tool.groups to activate the dap group for debugging."

1. Deactivation: Remove groups when done to reduce context.

"Use tool.groups to reset all active groups."

The server sends notifications/tools/list_changed so MCP clients (Claude Code, Claude Desktop) automatically refresh the tool list. If your MCP client caches tools aggressively and does not refresh after activation, reconnect the client or call the newly activated tool directly once to force a fresh tools/list round-trip.

Typed property values for scene tools

Bridge-backed scene tools (add_node, set_node_properties) now coerce common vector payloads such as { "x": 100, "y": 200 } and [100, 200] for typed properties like position and scale. Tagged values are still the safest cross-tool form:

{

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

The internal headless serializer uses _type, but MCP callers should prefer type when they need an explicit cross-tool Godot value tag.

Don't worry about tokens

GoPeak uses cursor-based pagination for tools/list — even in full profile, tools are delivered in pages (default 33) instead of dumping the entire legacy definition set at once. Your AI client fetches the next page only when it needs more.

Set page size with GOPEAK_TOOLS_PAGE_SIZE:

{

"env": { "GOPEAK_TOOLS_PAGE_SIZE": "25" } }

---

Installation Options

A) Recommended: npx

npx -y gopeak

B) Global install

npm install -g gopeak

gopeak

Optional shell hooks for update notifications remain available via:

gopeak setup

C) From source

git clone https://github.com/HaD0Yun/Gopeak-godot-mcp.git

cd godot-mcp npm install npm run build node build/index.js

GoPeak also exposes two CLI bin names:

• gopeak
• godot-mcp

---

Documentation

• Documentation Map
• Architecture
• Platform Roadmap
• Unity-MCP Benchmark Plan
• Release Process

CI

GitHub Actions runs on push/PR and executes:

1. npm run build
2. npx tsc --noEmit
3. npm run smoke

Run the same checks locally before opening a PR:

npm run ci

npm run test:dynamic-groups npm run test:integration

---

Versioning & Release

Use the built-in bump script to keep package.json and server.json in sync:

node scripts/bump-version.mjs patch

node scripts/bump-version.mjs minor --dry-run

Full release checklist: docs/release-process.md.

---

Addons (Recommended)

Auto Reload + Editor Bridge + Runtime Addon installer

Install in your Godot project folder:

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

PowerShell:

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

Then enable plugins in Project Settings → Plugins (especially godot_mcp_editor for bridge-backed scene/resource tools).

---

Core Capabilities

These capabilities are grouped by workflow value. Optional-runtime/LSP/DAP/network groups require their setup gates before use; audit-required groups should be promoted only after fixture evidence.

• Project control: launch editor, run/stop project, capture debug output
• Scene editing: create scenes, add/delete/reparent nodes, edit properties
• Script workflows: create/modify scripts, inspect script structure
• Resources: create/modify resources, materials, shaders, tilesets
• Signals/animation: connect signals, build animations/tracks/state machines
• Runtime tools: inspect live tree, set properties, call methods, metrics (requires runtime addon/socket)
• LSP + DAP: diagnostics/completion/hover + breakpoints/step/stack trace (requires Godot LSP/DAP ports)
• Input + screenshots: keyboard/mouse/action injection and viewport capture (requires runtime/editor bridge setup)
• Asset library: search/fetch CC0 assets (optional network/provider workflow)

Tool families (examples