How do I install Gopeak?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Gopeak need an API key?

No required environment variable is listed on this record.

What transport does Gopeak use?

Gopeak runs locally over stdio.

When was Gopeak last checked?

Last checked 2026-11-09. GoPeak — The most comprehensive MCP server for Godot Engine. 95+ tools, LSP, DAP, screenshots.

Gopeak MCP server

GoPeak

GoPeak Hero

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:

Group	Maturity	Description / setup gate
`scene_advanced`	audit-required	Duplicate, reparent nodes, load sprites; verify scene ownership/persistence in a Godot 4 fixture before treating as trusted.
`uid`	audit-required	UID management for resources; gate behavior by Godot version and resource save/load evidence.
`import_export`	audit-required	Import pipeline, reimport, validate project; requires fixture checks for import settings and export command construction.
`autoload`	audit-required	Autoload singletons, main scene; requires project settings round-trip verification.
`signal`	audit-required	Disconnect signals, list connections; requires signal round-trip verification.
`runtime`	optional-runtime	Live scene inspection, runtime properties, metrics; requires the runtime addon/socket.
`resource`	audit-required	Create/modify materials, shaders, resources; requires resource save/load fixture checks.
`animation`	audit-required	Animations, tracks, animation tree, state machine; requires saved scene/resource fixture checks.
`plugin`	optional-editor	Enable/disable/list editor plugins; requires editor plugin availability.
`input`	audit-required	Input action mapping; requires project settings round-trip verification.
`tilemap`	audit-required	TileSet and TileMap cell painting; must account for Godot 4.3+ `TileMapLayer` behavior before being promoted.
`audio`	audit-required	Audio buses, effects, volume; requires bus layout fixture checks.
`navigation`	audit-required	Navigation regions and agents; requires saved scene/resource fixture checks.
`theme_ui`	audit-required	Theme colors, font sizes, shaders; requires resource save/load fixture checks.

How it works:

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

"Use tool.catalog with query animation and show relevant tools."
Manual activation: Directly activate a group with tool.groups.

"Use tool.groups to activate the dap group for debugging."
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

CI

GitHub Actions runs on push/PR and executes:

npm run build
npx tsc --noEmit
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)

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.

Project Visualizer — AI-generated architecture map

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

Migration & Deprecation Policy

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

an old → new mapping or an explicit no-replacement note;
the profile impact (compact, full, legacy, or opt-in group);
whether an alias remains and the planned removal window;
README/docs and release-note updates;
a verification command proving tools/list exposure and alias behavior;
a migration prompt example for common Godot workflows.

Current compatibility stance: legacy tool names and compact aliases remain supported. Dynamic groups with optional external requirements (runtime, testing, lsp, dap, asset_store) should be documented as opt-in/setup-gated rather than marketed as always-available core behavior.

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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Gopeak?

Does Gopeak need an API key?

What transport does Gopeak use?

When was Gopeak last checked?

Documentation

GoPeak

Quick Start (3 Minutes)

Requirements

1) Run GoPeak

2) Add MCP client config

3) First prompts to try

Why GoPeak

Best For

Tool Surface Model (Important)

Dynamic Tool Groups (compact mode)

Typed property values for scene tools

Don't worry about tokens

Installation Options

A) Recommended: npx

B) Global install

C) From source

Documentation

CI

Versioning & Release

Addons (Recommended)

Auto Reload + Editor Bridge + Runtime Addon installer

Core Capabilities

Tool families (examples)

Project Visualizer

Quick Prompt Examples

Build

Debug

Runtime testing

Discovery & dynamic groups

Migration & Deprecation Policy

Technical Reference

Environment variables

Ports

Minimal port profiles

Troubleshooting

Docs & Project Links

License

Credits