gdharness Godot MCP Server: Setup for Claude, Cursor and Other Apps

• Checks whether the Godot editor and your running game are connected

  Reports whether the editor addon is connected, which Godot answers, whether the editor is playing something, and which running games it can reach. It is the first thing to call when nothing seems to answer.

  Try: “Is the Godot editor connected to the assistant?”

  Read · editor_status

• Summarizes the project: name, main scene, counts and health

  Returns the project's name and main scene, the Godot version, and counts of scenes, scripts and assets. Extra sections add autoloads, script classes, input actions, a health report and export validation.

  Try: “What is in this project and is it healthy?”

  Read · project_info

• Searches text across all project files

  Finds a word or regular expression in project files and returns the file and line of each match. It skips hidden folders, node_modules, folders with a .gdignore and the addons gdharness installed.

  Try: “Find everywhere the player_died signal is mentioned”

  Read · project_search

• Shows what a resource uses, or what uses it

  Lists the resources a file depends on, or the files that depend on it, which helps before moving or changing something.

  Try: “What scenes use the coin.png texture?”

  Read · project_dependencies

• Reads and changes project settings, autoloads, inputs, plugins and audio (16 ops)

  Reads one setting or a whole group, and writes settings in project.godot and the audio bus layout. Its 16 ops include unset, set_main_scene, add and remove autoload, add and remove input action, enable and disable plugin, and several audio bus changes.

  Try: “Add an input action called dash bound to the shift key”

  Delete · project_settings

• Checks and re-runs Godot's asset import (7 ops)

  Lists resources that are outdated or failed to import, shows or changes a resource's import options, reads UIDs, and reimports. Ops are status, options, set_options, reimport, uid, refresh_uids and refresh_classes.

  Try: “Which textures failed to import and why?”

  Runs code · project_import

• Lists, edits and runs export presets (5 ops)

  Reads the presets in export_presets.cfg, adds, changes or removes them, and runs an export with a preset. Ops are list, run, add_preset, set_preset and remove_preset.

  Try: “Export the Windows build with the release preset”

  Delete · project_export

• Runs the project's gdUnit4 tests and reports failures

  Runs the project's gdUnit4 suites in one engine and returns only the cases that did not pass, with where each is and what the assertion said. gdUnit4 must already be installed in the project.

  Try: “Run the tests for the inventory scripts”

  Runs code · project_test

• Creates or saves a scene file (3 ops)

  Makes a new scene with one root node, saves a scene, or saves a copy under a new path. Ops are create, save and save_as.

  Try: “Create a scene called shop.tscn with a Control root”

  Write · scene_create

• Shows the nodes in a scene file

  Lists a scene's node names, classes and hierarchy, with properties when asked, and notes which nodes are instances of other scenes.

  Try: “Show the node tree of the main menu scene”

  Read · scene_tree

• Adds, edits, moves and deletes nodes in a scene (8 ops)

  Works on one node in a scene file. Ops are add, get, set, duplicate, reparent, delete, set_tilemap_cells and bake_navigation, so it can also paint tiles and bake navigation regions.

  Try: “Add a Timer node named SpawnTimer under the root of level1.tscn”

  Delete · scene_node

• Lists, connects and removes signal connections in a scene (3 ops)

  Shows every signal connection in a scene, connects a signal to a method, or removes a connection. Ops are list, connect and disconnect.

  Try: “Connect the button's pressed signal to _on_buy_pressed”

  Delete · scene_signal

• Reads and edits animations and animation state machines (12 ops)

  Reads an AnimationPlayer's animations and an AnimationTree's states, and creates, changes or removes animations, tracks, states and transitions. Ops include create, add_track, remove_track, rename, remove, add_state and connect_states.

  Try: “Add a fade-in animation of 0.5 seconds to the menu AnimationPlayer”

  Delete · scene_animation

• Creates GDScript files and adds code to them (3 ops)

  Creates a script from content or a template, adds typed functions, variables and signals to an existing script, or renames a class or member across the project. Ops are create, modify and rename.

  Try: “Create a state machine script for the enemy”

  Write · script_edit

• Reads the structure of a script, or asks the language server (4 ops)

  Returns a script's functions, variables and signals from the file, or symbols, completions and hover text from the editor's language server. Ops are structure, symbols, completion and hover.

  Try: “List the functions in player.gd”

  Read · script_info

• Checks scripts for errors and warnings

  Asks the editor's language server for errors and warnings in one or more scripts. With no editor open it compiles them in a short headless Godot run instead and says so.

  Try: “Check all scripts under scripts/ for errors”

  Runs code · script_diagnostics

• Reads and edits resource files, themes, shaders and tilesets (9 ops)

  Reads a resource file's properties, creates or changes .tres resources, writes shaders, builds TileSets, edits Theme colours and font sizes, removes theme items, and moves or renames files while updating references. Ops are read, create, modify, create_shader, create_tileset, set_theme_color, set_theme_font_size, remove_theme_item and move.

  Try: “Create a red StandardMaterial3D called danger.tres”

  Delete · resource_edit

• Opens, restarts or closes the Godot editor (4 ops)

  Opens the editor on a project, restarts or closes the connected one (closing saves open scenes), or rebinds its debug adapter. Ops are open, restart, close and rebind.

  Try: “Open the editor on this project”

  Runs code · editor_launch

• Runs your game, checks that it boots, or profiles it (5 ops)

  Starts the project, stops it, boots it once headless to see whether it comes up clean, waits for it to end, or profiles where time goes by function. It can also run an exported build inside the project. Ops are start, check, stop, wait and profile.

  Try: “Run the game and tell me if it boots cleanly”

  Runs code · editor_run

• Reads what the game or the editor printed (2 ops)

  Returns console output as entries with a severity, including each error and warning with where it happened. Ops are run, for the game, and editor, for the editor itself.

  Try: “Show the errors from the last run”

  Read · editor_output

• Makes the editor pick up files changed outside it

  Asks the running editor to rescan the project files so edits made on disk are noticed, waiting out any scan or import already under way.

  Try: “Tell the editor to rescan the project”

  Write · editor_rescan

• Takes a picture of a scene as the editor draws it

  Captures a scene in the editor's 2D or 3D view, including what @tool scripts draw. It can also save the picture as a new PNG outside the project.

  Try: “Show me how level1 looks in the 3D view”

  Write · editor_capture

• Looks up Godot classes and your own script classes (3 ops)

  Finds engine and project classes, shows the methods, properties, signals and enums of one class, or walks its inheritance tree. Ops are query, info and inheritance.

  Try: “What signals does Area2D have?”

  Read · editor_classes

• Reads what the running game shows and holds (7 ops)

  Reads the live scene tree, all text on screen, nodes matching a query, a node's screen position, a property value, performance metrics and accessibility info. Ops are tree, text, find, rect, property, metrics and accessibility. Needs the game running with the runtime addon.

  Try: “What does the shop panel say right now?”

  Read · runtime_inspect

• Sets properties or calls methods in the running game (3 ops)

  Sets a property or calls a method on a node in the running game and returns the result. Ops are set, call and result, and result collects a reply that took too long.

  Try: “Set the player's health to 1 and see what happens”

  Runs code · runtime_invoke

• Takes a screenshot of the running game (2 ops)

  Captures the whole game window, a region or node, or one viewport as an image, and can also save a PNG outside the project. Ops are screenshot and viewport.

  Try: “Take a screenshot of the game”

  Write · runtime_capture

• Clicks, types and presses keys in the running game (12 ops)

  Sends input to the running game: clicks by node path or by the words on a control, menu choices, typing, actions, keys, mouse moves and drags, touch, and joypad buttons and sticks. Ops include click, choose, action, key, text, mouse_drag, touch and joypad_motion.

  Try: “Click the button that says Buy”

  Write · runtime_input

• Waits for something to happen in the running game (5 ops)

  Lets the game run until a number of frames pass, a signal fires, a property reaches a value or words appear on screen, and can record changes in between. Ops are frames, signal, watch, recorded and until.

  Try: “Wait until the score reads 100”

  Read · runtime_wait

• Sets, removes and lists breakpoints (3 ops)

  Sets or removes breakpoints in scripts, and lists the ones held. Setting one on a line with no code is refused. Ops are set, remove and list.

  Try: “Set a breakpoint on line 42 of player.gd”

  Write · debug_breakpoint

• Pauses, resumes and steps the debugged game (5 ops)

  Pauses the game, continues after a breakpoint, or steps over, into or out of a line, and returns the stack where it stops. Ops are pause, continue, step_over, step_into and step_out.

  Try: “Step over the current line and show the stack”

  Write · debug_control

• Reads the stack, variables and console of a stopped game (4 ops)

  Shows the stack trace, locals and members at a frame, the debugger's console output, and works out an expression in the held game. Ops are stack, variables, evaluate and output.

  Try: “What are the variables at the breakpoint?”

  Runs code · debug_state

Watch out for

• It runs your game and can call code inside it

  runtime_invoke calls methods and sets properties in the running game, debug_state can evaluate expressions, and editor_run starts the project or an exported build in it with arguments. Only open projects you trust. npmjs.com

• It edits and moves your project files

  Scene, script, resource and settings tools write to your project, and resource_edit move moves files and rewrites references. Our advice: commit before a session so you can review and revert. npmjs.com

• Setup writes addons and config into your project

  The setup command installs four addons, enables two editor plugins, adds a GdharnessRuntime autoload in project.godot, rebuilds the class list, writes a skill into .agents/skills (with copies for Claude Code, Kiro and Cline) and registers the server in the assistant configs the project already uses. Use the no-connect, no-skill or no-runtime flags to skip parts. aureliolo.github.io

• Machine-wide configs are written only when you ask

  Claude Desktop, Codex, Cline and Windsurf have no project config, so setup writes them only with their flag or a typed yes. That changes every project you open with that app. aureliolo.github.io

• Local ports are open while it runs

  The editor bridge listens on 127.0.0.1:6505 by default. The runtime addon in your game also listens on 127.0.0.1 in debug builds only, and its code says its commands are not authenticated. Do not change the bind address to a public one. github.com

• Screenshot tools can save a PNG outside the project

  editor_capture and runtime_capture can write a new PNG to an absolute path outside the project, and refuse to overwrite an existing file. npmjs.com

• It checks the npm registry for updates

  Tool answers can carry an update notice with an upgrade command, and the upgrade replaces the addons in your project. The install guide tells the assistant to run it only with your agreement. aureliolo.github.io

Security advisories