godot-mcp-runtime 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Owen Sterling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Godot Runtime MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server that gives AI assistants direct access to a running Godot 4.x game. Not just file editing, not just scene manipulation, but actual runtime control: input simulation, screenshots, UI discovery, and live GDScript execution while the game is running.
+
+Most Godot MCP servers operate headlessly. They can create scenes, add nodes, attach scripts, and that covers a lot of ground. But they stop at the editor boundary. This one doesn't. When you run a project through this server, it injects a lightweight UDP bridge as an autoload, and suddenly the AI can interact with your game the same way a player would. It presses keys, clicks buttons, reads what's on screen, and runs arbitrary code against the live scene tree.
+
+The distinction matters: the AI doesn't just write your game, it can test it.
+
+## What It Does
+
+**Headless editing**: Create scenes, add nodes, set properties, attach scripts, manage UIDs. All the standard operations you'd expect, no editor window required.
+
+**Runtime bridge**: When `run_project` is called, the server injects `McpBridge` as an autoload. This opens a UDP channel on port 9900 and enables:
+
+- **Screenshots**: Capture the viewport at any point during gameplay
+- **Input simulation**: Batched sequences of key presses, mouse clicks and movement, UI element clicks by name or path, Godot action presses, and timed waits
+- **UI discovery**: Walk the live scene tree and collect every visible Control node with its position, type, text content, and disabled state
+- **Live script execution**: Compile and execute arbitrary GDScript with full SceneTree access while the game is running
+
+The bridge cleans itself up automatically when `stop_project` is called. No leftover autoloads, no modified project files.
+
+## Quick Start
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) v18+
+- [Godot 4.x](https://godotengine.org/)
+
+### Install
+
+```bash
+git clone https://github.com/Erodenn/godot-mcp-runtime.git
+cd godot-mcp-runtime
+npm install
+npm run build
+```
+
+### Configure Your MCP Client
+
+Add the following to your MCP client config. This works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "godot": {
+      "command": "node",
+      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
+      "env": {
+        "GODOT_PATH": "<path-to-godot-executable>"
+      }
+    }
+  }
+}
+```
+
+If Godot is on your `PATH`, you can omit `GODOT_PATH` entirely. The server will auto-detect it.
+
+Set `"DEBUG": "true"` in `env` for verbose logging.
+
+### Verify
+
+Ask your AI assistant to call `get_project_info`. If it returns a Godot version string (e.g., `4.4.stable`), you're connected and working.
+
+## Tools
+
+### Project
+
+| Tool | Description |
+|------|-------------|
+| `launch_editor` | Open the Godot editor for a project |
+| `run_project` | Run a project and inject the MCP bridge |
+| `stop_project` | Stop the running project and clean up the bridge |
+| `get_debug_output` | Read stdout/stderr from the running project |
+| `list_projects` | Find Godot projects in a directory |
+| `get_project_info` | Get project metadata, or just the Godot version if no project path is given |
+
+### Runtime (requires `run_project` first)
+
+| Tool | Description |
+|------|-------------|
+| `take_screenshot` | Capture a PNG of the running viewport |
+| `simulate_input` | Batched input: key, mouse_button, mouse_motion, click_element, action, wait |
+| `get_ui_elements` | Get visible Control nodes with positions, types, and text |
+| `run_script` | Execute GDScript at runtime with full SceneTree access |
+
+### Scene: `manage_scene`
+
+| Operation | Description |
+|-----------|-------------|
+| `create` | Create a new scene file |
+| `add_node` | Add a node to an existing scene |
+| `load_sprite` | Set a texture on a Sprite2D, Sprite3D, or TextureRect |
+| `save` | Save a scene, or save-as with `newPath` |
+| `export_mesh_library` | Export scenes as a MeshLibrary for GridMap |
+
+### UIDs: `manage_uids` (Godot 4.4+)
+
+| Operation | Description |
+|-----------|-------------|
+| `get` | Get a resource's UID |
+| `update` | Resave all resources to update UID references |
+
+### Node: `manage_node`
+
+| Operation | Description |
+|-----------|-------------|
+| `delete` | Remove a node from a scene |
+| `update_property` | Set a property on a node |
+| `get_properties` | Read node properties |
+| `attach_script` | Attach a GDScript to a node |
+| `list` | List child nodes |
+| `get_tree` | Get the full scene tree hierarchy |
+
+## Architecture
+
+```
+src/
+├── index.ts                # MCP server entry point, routes tool calls
+├── tools/
+│   ├── project-tools.ts    # Project and runtime tool handlers
+│   ├── scene-tools.ts      # Scene operations
+│   └── node-tools.ts       # Node operations
+├── scripts/
+│   ├── godot_operations.gd # Headless GDScript operations
+│   └── mcp_bridge.gd       # UDP autoload for runtime communication
+└── utils/
+    └── godot-runner.ts     # Process spawning, output parsing
+```
+
+Headless operations spawn Godot with `--headless --script godot_operations.gd`, perform the operation, and return JSON.
+
+Runtime operations communicate over UDP with the injected `McpBridge` autoload in the running game.
+
+## How the Bridge Works
+
+When `run_project` is called:
+
+1. `mcp_bridge.gd` is copied into the project directory
+2. It's registered as an autoload in `project.godot`
+3. The project launches with the bridge listening on UDP port 9900
+4. Runtime tools send JSON commands to the bridge and await responses
+5. When `stop_project` is called, the autoload entry and bridge script are removed
+
+Files generated during runtime (screenshots, executed scripts) are stored in `.mcp/` inside the project directory. This directory is automatically added to `.gitignore` and has a `.gdignore` so Godot won't import it.
+
+## Acknowledgments
+
+Built on the foundation laid by [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) for headless Godot operations.
+
+Developed with [Claude Code](https://claude.ai/code).
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Godot MCP Server
+ *
+ * This MCP server provides tools for interacting with the Godot game engine.
+ * It enables AI assistants to launch the Godot editor, run Godot projects,
+ * capture debug output, manipulate scenes and nodes, and more.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Godot MCP Server
+ *
+ * This MCP server provides tools for interacting with the Godot game engine.
+ * It enables AI assistants to launch the Godot editor, run Godot projects,
+ * capture debug output, manipulate scenes and nodes, and more.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { GodotRunner } from './utils/godot-runner.js';
+// Project tools
+import { projectToolDefinitions, handleLaunchEditor, handleRunProject, handleGetDebugOutput, handleStopProject, handleListProjects, handleGetProjectInfo, handleTakeScreenshot, handleSimulateInput, handleGetUiElements, handleRunScript, } from './tools/project-tools.js';
+// Scene tools
+import { sceneToolDefinitions, handleManageScene, handleManageUids, } from './tools/scene-tools.js';
+// Node tools
+import { nodeToolDefinitions, handleManageNode, } from './tools/node-tools.js';
+class GodotMcpServer {
+    server;
+    runner;
+    constructor(config) {
+        this.runner = new GodotRunner(config);
+        this.server = new Server({
+            name: 'godot-mcp',
+            version: '0.3.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+        this.server.onerror = (error) => console.error('[MCP Error]', error);
+        process.on('SIGINT', async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+    }
+    async cleanup() {
+        console.error('[SERVER] Cleaning up resources');
+        this.runner.stopProject();
+        await this.server.close();
+    }
+    setupToolHandlers() {
+        // Combine all tool definitions
+        const allTools = [
+            ...projectToolDefinitions,
+            ...sceneToolDefinitions,
+            ...nodeToolDefinitions,
+        ];
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: allTools,
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const toolName = request.params.name;
+            const args = request.params.arguments || {};
+            console.error(`[SERVER] Handling tool request: ${toolName}`);
+            switch (toolName) {
+                // Project tools
+                case 'launch_editor':
+                    return await handleLaunchEditor(this.runner, args);
+                case 'run_project':
+                    return await handleRunProject(this.runner, args);
+                case 'get_debug_output':
+                    return handleGetDebugOutput(this.runner, args);
+                case 'stop_project':
+                    return handleStopProject(this.runner);
+                case 'list_projects':
+                    return await handleListProjects(args);
+                case 'get_project_info':
+                    return await handleGetProjectInfo(this.runner, args);
+                case 'take_screenshot':
+                    return await handleTakeScreenshot(this.runner, args);
+                case 'simulate_input':
+                    return await handleSimulateInput(this.runner, args);
+                case 'get_ui_elements':
+                    return await handleGetUiElements(this.runner, args);
+                case 'run_script':
+                    return await handleRunScript(this.runner, args);
+                // Scene tools
+                case 'manage_scene':
+                    return await handleManageScene(this.runner, args);
+                case 'manage_uids':
+                    return await handleManageUids(this.runner, args);
+                // Node tools
+                case 'manage_node':
+                    return await handleManageNode(this.runner, args);
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+            }
+        });
+    }
+    async run() {
+        try {
+            await this.runner.detectGodotPath();
+            const godotPath = this.runner.getGodotPath();
+            if (!godotPath) {
+                console.error('[SERVER] Failed to find a valid Godot executable path');
+                console.error('[SERVER] Please set GODOT_PATH environment variable or provide a valid path');
+                process.exit(1);
+            }
+            console.error(`[SERVER] Using Godot at: ${godotPath}`);
+            const transport = new StdioServerTransport();
+            await this.server.connect(transport);
+            console.error('Godot MCP server running on stdio');
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            console.error('[SERVER] Failed to start:', errorMessage);
+            process.exit(1);
+        }
+    }
+}
+// Create and run the server
+const server = new GodotMcpServer();
+server.run().catch((error) => {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    console.error('Failed to run server:', errorMessage);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}