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 33 core tools with 22 dynamic tool groups (78 additional tools) that activate on demand — keeping token usage low while preserving full capability.

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.
• 110+ tools available across scene/script/resource/runtime/LSP/DAP/input/assets.
• Token-efficient by default: compact tool surface (33 tools) + dynamic tool groups. Only activate what you need — no more 110-tool context bombs.
• Dynamic tool groups: search with tool.catalog and matching groups auto-activate. Or manually activate with tool.groups.
• Deep Godot integration: ClassDB queries, runtime inspection, debugger hooks, bridge-based scene/resource edits.

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): 33 core tools + 22 dynamic tool groups (78 additional tools activated on demand)
• full: exposes full legacy tool list (110+)
• legacy: same exposed behavior as full

Configure with either:

• GOPEAK_TOOL_PROFILE
• MCP_TOOL_PROFILE (fallback alias)

Dynamic Tool Groups (compact mode)

In compact mode, 78 additional tools are organized into 22 groups that activate automatically when needed:

Group	Tools	Description
scene_advanced	3	Duplicate, reparent nodes, load sprites
uid	2	UID management for resources
import_export	5	Import pipeline, reimport, validate project
autoload	4	Autoload singletons, main scene
signal	2	Disconnect signals, list connections
runtime	4	Live scene inspection, runtime properties, metrics
resource	4	Create/modify materials, shaders, resources
animation	5	Animations, tracks, animation tree, state machine
plugin	3	Enable/disable/list editor plugins
input	1	Input action mapping
tilemap	2	TileSet and TileMap cell painting
audio	4	Audio buses, effects, volume
navigation	2	Navigation regions and agents
theme_ui	3	Theme colors, font sizes, shaders
asset_store	3	Search/download CC0 assets
testing	6	Screenshots, viewport capture, input injection
dx_tools	4	Error log, project health, find usages, scaffold
intent_tracking	9	Intent capture, decision logs, handoff briefs
class_advanced	1	Class inheritance inspection
lsp	3	GDScript completions, hover, symbols
dap	6	Breakpoints, stepping, stack traces
version_gate	2	Version validation, patch verification

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

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

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

3. 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 all 110+ definitions 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

• 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
• LSP + DAP: diagnostics/completion/hover + breakpoints/step/stack trace
• Input + screenshots: keyboard/mouse/action injection and viewport capture
• Asset library: search/fetch CC0 assets (Poly Haven, AmbientCG, Kenney)

Tool families (examples)

Area	Examples
Project	project.list, project.info, editor.run
Scene/Node	scene.create, scene.node.add, set_node_properties
Script	script.create, script.modify, script.info
Runtime	runtime.status, inspect_runtime_tree, call_runtime_method
LSP/DAP	lsp.diagnostics, lsp_get_hover, dap_set_breakpoint, dap.output
Input/Visual	inject_key, inject_mouse_click, capture_screenshot

---

Project Visualizer

Visualize your entire project architecture with visualizer.map (map_project legacy). Scripts are grouped by folder structure into color-coded categories.

---

Quick Prompt Examples

Build

• "Create a Player scene with CharacterBody2D, Sprite2D, CollisionShape2D, and a basic movement script."
• "Add an enemy spawner scene and wire spawn signals to GameManager."

Debug

• "Run the project, collect errors, and fix the top 3 issues automatically."
• "Set a breakpoint at scripts/player.gd:42, continue execution, and show stack trace when hit."

Runtime testing

• "Press ui_accept, move mouse to (400, 300), click, then capture a screenshot."
• "Inspect live scene tree and report nodes with missing scripts or invalid references."

Discovery & dynamic groups

• "Use tool.catalog with query tilemap and list the most relevant tools."
• "Activate the dap tool group for breakpoint debugging with tool.groups."
• "Find import pipeline tools with tool.catalog query import and run the best one for texture settings."
• "Reset all active tool groups with tool.groups to reduce context."

---

Technical Reference

Environment variables

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 (aliases: MCP_BRIDGE_PORT, GOPEAK_BRIDGE_PORT)	6505
DEBUG	Enable server debug logs (true/false)	false
LOG_MODE	Recording mode: lite or full	lite
GOPEAK_TOOLS_PAGE_SIZE	Number of tools per tools/list page (pagination)	33
GOPEAK_BRIDGE_PORT	Port for unified bridge/visualizer server	6505
GOPEAK_BRIDGE_HOST	Bind host for bridge/visualizer server	127.0.0.1

Ports

Port	Service
6505 (default)	Unified Godot Bridge + Visualizer server (+ /health, /mcp) on loopback by default
6005	Godot LSP
6006	Godot DAP
7777	Runtime addon command socket (only needed for runtime tools)

Minimal port profiles

• Core editing only: bridge port (GODOT_BRIDGE_PORT, default 6505)
• Core + runtime actions (screenshots/input/runtime inspect): bridge port + 7777
• Full debugging + diagnostics: bridge port + 6005 + 6006 + 7777

---

Troubleshooting

• Godot not found → set GODOT_PATH
• No MCP tools visible → restart your MCP client
• Project path invalid → confirm project.godot exists
• Runtime tools not working → install/enable runtime addon plugin
• Need a tool that is not visible → run tool.catalog to search and auto-activate matching groups, or use tool.groups to activate a specific group
• get_editor_status says disconnected while the Godot editor shows connected → check whether another gopeak/MCP server instance already owns bridge port 6505; the status payload now reports the startup error and suggests stopping duplicate servers

---

Docs & Project Links

• Architecture (MCP Platform Direction)
• Platform Roadmap (P1/P2/P3)
• CHANGELOG
• ROADMAP
• CONTRIBUTING

---

License

MIT — see LICENSE.

Credits

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