GoPeak
Provides project control, scene/script editing, resource workflows, debugging, and runtime testing for Godot 4 projects through an MCP server interface.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GoPeak List Godot projects in /my/projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GoPeak
🌐 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.4.1/gopeak-2.4.1.tgzThat 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.4.1/gopeak-2.4.1.tgz
curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.4.1/gopeak-2.4.1.tgz.sha256
if command -v sha256sum >/dev/null 2>&1; then
sha256sum -c gopeak-2.4.1.tgz.sha256
else
shasum -a 256 -c gopeak-2.4.1.tgz.sha256
fi
bun add -g "$PWD/gopeak-2.4.1.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.shThe 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/projectsand show project info.""Create
scenes/Player.tscnwith aCharacterBody2Droot and a movement script.""Run the project, read the debug output, and fix the top error."
"Use
tool.catalogto find animation tools, then activate the right group."
Related MCP server: AI-godot-mcp
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 |
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 |
|
Runtime inspection, screenshots, input injection | Runtime addon/socket, default port |
GDScript LSP tools | Godot LSP enabled on port |
DAP debugging tools | Godot DAP enabled on port |
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 | bashPowerShell:
iwr https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.ps1 -UseBasicParsing | iexThen enable plugins in Project Settings → Plugins:
godot_mcp_editorfor bridge-backed scene/resource toolsgodot_mcp_runtimefor runtime inspection, screenshots, and input workflows
Optional shell hooks for update notifications are opt-in:
gopeak setupgopeak 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 |
| Default. Trusted core tools plus dynamic groups activated on demand. |
| Compatibility/audit mode for the full legacy surface. |
| Older config alias with the same exposed behavior as |
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 |
| optional-runtime | Live scene tree, properties, method calls, metrics. Requires runtime addon/socket. |
| optional-runtime | Screenshots, viewport capture, input injection. Requires runtime/editor setup. |
| optional-lsp | Diagnostics, completion, hover, symbols. Requires Godot LSP on port |
| optional-dap | Breakpoints, stepping, stack traces. Requires Godot DAP on port |
| optional-network | External CC0 asset search/download. Network/provider dependent. |
| trusted-static | ClassDB/inheritance discovery backed by static engine metadata. |
| audit-required | Must account for Godot 4.3+ |
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. |
| 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:packagingCLI bin names:
gopeakgodot-mcp
Environment & Ports
Name | Purpose | Default |
| Tool exposure profile: |
|
| Fallback profile env alias |
|
| Explicit Godot executable path | auto-detect |
| Bridge/Visualizer HTTP+WS port override |
|
| Bridge/Visualizer bind host |
|
| Number of tools per |
|
| Runtime addon command timeout in milliseconds |
|
| Enable server debug logs |
|
| Recording mode: |
|
Port | Service |
| Unified Godot Bridge + Visualizer server on loopback by default. |
| Godot LSP. |
| Godot DAP. |
| 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.catalogor activate a group withtool.groups.Project path invalid → confirm
project.godotexists.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_pathflow. For slow runtime responses, raiseGOPEAK_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 port6505;get_editor_statusreports bridge startup errors such asEADDRINUSE.
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:
old → new mapping or an explicit no-replacement note;
profile impact (
compact,full,legacy, or opt-in group);alias window and planned removal timing;
README/docs and release-note updates;
verification proving
tools/listexposure and alias behavior;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
License & Credits
MIT — see LICENSE.
Original MCP server by Coding-Solo
GoPeak enhancements by HaD0Yun
Project visualizer inspired by tomyud1/godot-mcp
Available Tools
33 toolsclass-infoA
[compact alias of query_class_info] Get detailed information about a specific Godot class: methods, properties, signals, enums. Use to discover available properties before calling add_node/create_resource/set_node_properties, or to find methods before call_runtime_method.
Inputs: className (required), projectPath (required), includeInherited.
class-queryA
[compact alias of query_classes] Query available Godot classes from ClassDB with filtering. Use to discover node types, resource types, or any class before using add_node/create_resource. Categories: node, node2d, node3d, control, resource, physics, physics2d, audio, visual, animation.
Inputs: projectPath (required), filter, category, instantiableOnly.
dap-outputB
[compact alias of dap_get_output] Get captured Godot DAP console output lines
Inputs: no named parameters.
editor-debug-outputA
[compact alias of get_debug_output] Retrieves console output and errors from the currently running Godot project. Use after run_project to check logs, errors, and print statements. Returns empty if no project is running.
Inputs: reason (required).
editor-launchA
[compact alias of launch_editor] Opens the Godot editor GUI for a project. Use when visual inspection or manual editing of scenes/scripts is needed. Opens a new window on the host system. Requires: project directory with project.godot file.
Inputs: projectPath (required).
editor-runA
[compact alias of run_project] Launches a Godot project in a new window and captures output. Use to test gameplay or verify script behavior. Runs until stop_project is called. Use get_debug_output to retrieve logs.
Inputs: projectPath (required), scene.
editor-statusA
[compact alias of get_editor_status] Returns the connection status of the Godot Editor Plugin bridge. Use to check if the editor is connected before using scene/resource tools that require the editor plugin.
Inputs: no named parameters.
editor-stopA
[compact alias of stop_project] Terminates the currently running Godot project process. Use to stop a project started with run_project. No effect if no project is running.
Inputs: reason (required).
editor-versionA
[compact alias of get_godot_version] Returns the installed Godot engine version string. Use to check compatibility (e.g., Godot 4.4+ features like UID). Returns version like "4.3.stable" or "4.4.dev".
Inputs: reason (required).
export-presetsA
[compact alias of list_export_presets] Lists all export presets defined in export_presets.cfg. Use before export_project to see available targets (Windows, Linux, Android, etc.).
Inputs: projectPath (required), includeTemplateStatus.
export-runA
[compact alias of export_project] Exports the project to a distributable format. Use to build final game executables. Requires export templates installed.
Inputs: preset (required), outputPath (required), projectPath (required), debug.
lsp-diagnosticsC
[compact alias of lsp_get_diagnostics] Get GDScript diagnostics from Godot Language Server for a script file.
Inputs: scriptPath (required), projectPath (required).
project-infoA
[compact alias of get_project_info] Returns metadata about a Godot project including name, version, main scene, autoloads, and directory structure. Use to understand project before modifying. Requires valid project.godot.
Inputs: projectPath (required).
project-listA
[compact alias of list_projects] Scans a directory for Godot projects (folders containing project.godot). Use to discover projects before using other tools. Returns array of {path, name}.
Inputs: directory (required), recursive.
project-searchA
[compact alias of search_project] Searches for text or regex patterns across project files. Use to find function usages, variable references, or TODOs. Returns file paths and line numbers.
Inputs: query (required), projectPath (required), regex, fileTypes, +2 more.
project-setting-getA
[compact alias of get_project_setting] Reads a value from project.godot settings. Use to check game name, window size, physics settings, etc.
Inputs: setting (required), projectPath (required).
project-setting-setA
[compact alias of set_project_setting] Writes a value to project.godot settings. Use to configure game name, window size, physics, etc.
Inputs: value (required), setting (required), projectPath (required).
resource-dependenciesA
[compact alias of get_dependencies] Analyzes resource dependencies and detects circular references. Use to understand what a scene/script depends on before refactoring.
Inputs: projectPath (required), resourcePath (required), depth, includeBuiltin.
runtime-statusA
[compact alias of get_runtime_status] Checks if a Godot game instance is running and connected for live debugging. Use before other runtime tools.
Inputs: projectPath (required).
scene-createA
[compact alias of create_scene] Creates a new Godot scene file (.tscn) with a specified root node type. Use to start building new game levels, UI screens, or reusable components. The scene is saved automatically after creation.
Inputs: scenePath (required), projectPath (required), rootNodeType.
scene-node-addA
[compact alias of add_node] Adds ANY node type to an existing scene. This is the universal node creation tool — replaces all specialized create_* node tools. Supports ALL ClassDB node types (Camera3D, DirectionalLight3D, AudioStreamPlayer, HTTPRequest, RayCast3D, etc.). Set any property via the properties parameter with type conversion support (Vector2, Vector3, Color, etc.). Use query_classes to discover available node types. Use query_class_info to discover available properties for a type.
Inputs: nodeName (required), nodeType (required), scenePath (required), projectPath (required), +2 more.
scene-node-deleteA
[compact alias of delete_node] Removes a node and all its children from a scene. Use to clean up unused nodes. Cannot delete root node. Scene is saved automatically unless saveScene=false.
Inputs: nodePath (required), scenePath (required), projectPath (required), saveScene.
scene-node-propertiesA
[compact alias of get_node_properties] Returns all properties of a specific node in a scene. Use to inspect current values before modifying. Returns property names, values, and types.
Inputs: nodePath (required), scenePath (required), projectPath (required), includeDefaults.
scene-nodesA
[compact alias of list_scene_nodes] Returns complete scene tree structure with all nodes, types, and hierarchy. Use to understand scene organization before modifying. Returns nested tree with node paths.
Inputs: scenePath (required), projectPath (required), depth, includeProperties.
scene-node-setA
[compact alias of set_node_properties] Sets multiple properties on a node in a scene. Prerequisite: scene and node must exist (use create_scene and add_node first). Use to modify position, scale, rotation, or any node-specific properties. Scene is saved automatically unless saveScene=false.
Inputs: nodePath (required), scenePath (required), properties (required), projectPath (required), +1 more.
scene-saveA
[compact alias of save_scene] Saves changes to a scene file or creates a variant at a new path. Most scene modification tools save automatically, but use this for explicit saves or creating variants.
Inputs: scenePath (required), projectPath (required), newPath.
script-createA
[compact alias of create_script] Creates a new GDScript (.gd) file with optional templates. Use to generate scripts for game logic. Templates: "singleton" (autoload), "state_machine" (FSM), "component" (modular), "resource" (custom Resource).
Inputs: scriptPath (required), projectPath (required), reason, content, +3 more.
script-infoA
[compact alias of get_script_info] Analyzes a GDScript and returns its structure: functions, variables, signals, class_name, extends. Use before modify_script to understand existing code.
Inputs: scriptPath (required), projectPath (required), includeInherited.
script-modifyA
[compact alias of modify_script] Adds functions, variables, or signals to an existing GDScript. Use to extend scripts without manual editing. Supports @export, @onready annotations and type hints.
Inputs: scriptPath (required), projectPath (required), modifications (required), reason.
signal-connectA
[compact alias of connect_signal] Creates a signal connection between nodes in a scene. Prerequisite: source and target nodes must exist. Use to wire up button clicks, collision events, custom signals. Saved to scene file.
Inputs: scenePath (required), methodName (required), signalName (required), projectPath (required), +3 more.
tool-catalogA
[compact alias of tool_catalog] Discover available tools including hidden legacy tools. Use query to search by capability keywords. Results include group categorization (core/dynamic). Matching dynamic groups are auto-activated and become available immediately. Core groups (always visible): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.
Inputs: limit, query.
tool-groupsA
[compact alias of manage_tool_groups] Manage tool groups. Actions: list (show all core + dynamic groups), activate (enable a dynamic group), deactivate (disable a dynamic group), reset (disable all dynamic), status (show current state). Core groups (always visible, 33 tools): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand, 78 tools): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.
Inputs: action (required), group.
visualizer-mapA
[compact alias of map_project] Crawl the entire Godot project and build an interactive visual map of all scripts showing their structure (variables, functions, signals), connections (extends, preloads, signal connections), and descriptions. Opens an interactive browser-based visualization at localhost:6505.
Inputs: projectPath (required), root, include_addons.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Tools are largely distinguished by domain prefix and action, but a few pairs overlap: editor-status vs runtime-status, editor-debug-output vs dap-output, and tool-catalog vs tool-groups. Descriptions help resolve most ambiguity, but an agent could still hesitate between editor/runtime status and debug output sources.
Names follow a consistent kebab-case, domain-prefixed convention (e.g., scene-node-add, project-setting-get, script-modify). Minor deviation: some entries are noun phrases (scene-nodes, runtime-status) while others are verb phrases (scene-create, script-create), but the pattern remains predictable.
33 visible core tools exceed the typical 3–15 well-scoped range, and the server also advertises 78 dynamic tools. The grouping mechanism mitigates this, but the visible set alone is still heavy and risks overwhelming an agent.
Core workflows for project, scene, script, class, signal, export, and editor are covered, but notable gaps remain: no resource creation/deletion, no signal disconnect, and no scene/script deletion in the visible set. The dynamic tool groups and tool-catalog provide a workaround, but the core surface is not fully self-contained.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.333MIT
- AlicenseCqualityCmaintenanceEnables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.2814 npmMIT
- AlicenseAqualityDmaintenanceProvides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.21MIT
- FlicenseAqualityBmaintenanceMCP server that connects AI coding assistants to a live Godot editor, enabling scene, node, script, resource, runtime, debugger, and test workflows through natural language.45-