Godette

MCP server for Godot game development. Provides 45 tools for reading, analyzing, and editing Godot projects through the Model Context Protocol.

Features

• Scene tools — traverse scene trees, find nodes by type/group/script, trace signal chains, query dependencies
• Scene editing — add/remove nodes, connect/disconnect signals, manage groups, modify properties
• Symbol tools — find and navigate GDScript symbols with LSP when available, regex parser as fallback
• Symbol editing — replace function bodies, insert before/after symbols with hash-verified safety
• Resource tools — find resources by type, inspect properties, trace cross-project references
• File tools — Godot-enriched file reads (parsed symbols for .gd, scene structure for .tscn)
• Runtime tools — run/stop scenes, capture game state, take screenshots, read console output (requires editor plugin)
• Memory tools — persistent key-value memory for project context across sessions

Prerequisites

• Node.js >= 20
• A Godot 4.x project
• (Optional) Godot editor running for LSP support
• (Optional) GDScript editor plugin for runtime tools

Installation

npm install godette

Or run directly:

npx godette

Usage

As an MCP server

Add to your MCP client configuration (e.g. Claude Desktop):

{
  "mcpServers": {
    "godette": {
      "command": "npx",
      "args": ["godette"],
      "env": {
        "GODOT_PROJECT": "/path/to/your/godot/project"
      }
    }
  }
}

The server auto-detects the Godot project root from the working directory or GODOT_PROJECT env var.

As a library

import { parseTscn, parseGdScript, UnifiedIndex, EventBus } from "godette";

// Parse a scene file
const scene = parseTscn(tscnSource, "/path/to/scene.tscn");
console.log(scene.rootType, scene.nodes.size);

// Parse a GDScript file
const script = parseGdScript(gdSource, "/path/to/script.gd");
console.log(script.className, script.functions.length);

Architecture

MCP Client (stdio)
    |
GodetteMcpServer
    |-- EventBus (typed async events)
    |-- ProjectDetector (finds project.godot)
    |-- FileWatcher (recursive fs.watch)
    |-- UnifiedIndex
    |     |-- SceneIndex
    |     |-- ScriptIndex
    |     |-- ResourceIndex
    |     |-- SignalGraph
    |     |-- GroupIndex / NodeTypeIndex
    |     '-- AutoloadIndex
    |-- ToolRegistry (45 tools, 8 categories)
    |-- Middleware (logging, timing, error handling)
    |-- LspClient (JSON-RPC, port 6005)
    '-- PluginClient (NDJSON, port 6006)

Key design decisions:

• Parsers are pure functions with no side effects
• Types are pure interfaces, barrel-exported from src/index.ts
• UnifiedIndex uses lazy recomputation via DirtyTracker
• TSCN parser is two-pass: tokenizer -> block parsers -> assembler
• Serializer preserves raw formatting for unmodified blocks

Available Tools (45)

File (7)

read_file list_dir find_file replace_content create_file delete_lines insert_at_line

Scene (8)

get_scene_tree find_node find_signal_connections find_group_members get_scene_dependencies trace_signal_chain find_scene_instances get_node_properties

Scene Edit (8)

add_node remove_node modify_node_property connect_signal disconnect_signal add_to_group remove_from_group create_scene

Symbol (4)

find_symbol find_references get_symbols_overview rename_symbol

Symbol Edit (3)

replace_symbol_body insert_after_symbol insert_before_symbol

Resource (4)

find_resource get_resource_properties get_resource_references find_resources_of_type

Project (5)

get_project_settings get_input_map get_layer_names get_autoloads list_project_structure

Runtime (8)

run_project stop_project capture_state get_runtime_state get_signal_log screenshot get_console_output get_live_scene_tree

Memory (5)

read_memory write_memory search_memories list_memories delete_memory

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run tests (vitest)
npm run test:watch   # Tests in watch mode
npm run lint         # ESLint
npm run format       # Prettier
npm run check        # Full CI check (typecheck + lint + test)

License

MIT