GoPeak

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

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.

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

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