Godot MCP

Instructions

Implementation Reference

• src/index.ts:1382-1478 (handler)

  Main handler function that implements the get_project_info tool logic. Validates input, checks project validity, retrieves Godot version, scans project structure, extracts project name from project.godot, and returns JSON with project metadata.
  private async handleGetProjectInfo(args: any) { // Normalize parameters to camelCase args = this.normalizeParameters(args); if (!args.projectPath) { return this.createErrorResponse( 'Project path is required', ['Provide a valid path to a Godot project directory'] ); } if (!this.validatePath(args.projectPath)) { return this.createErrorResponse( 'Invalid project path', ['Provide a valid path without ".." or other potentially unsafe characters'] ); } try { // Ensure godotPath is set if (!this.godotPath) { await this.detectGodotPath(); if (!this.godotPath) { return this.createErrorResponse( 'Could not find a valid Godot executable path', [ 'Ensure Godot is installed correctly', 'Set GODOT_PATH environment variable to specify the correct path', ] ); } } // Check if the project directory exists and contains a project.godot file const projectFile = join(args.projectPath, 'project.godot'); if (!existsSync(projectFile)) { return this.createErrorResponse( `Not a valid Godot project: ${args.projectPath}`, [ 'Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects', ] ); } this.logDebug(`Getting project info for: ${args.projectPath}`); // Get Godot version const execOptions = { timeout: 10000 }; // 10 second timeout const { stdout } = await execAsync(`"${this.godotPath}" --version`, execOptions); // Get project structure using the recursive method const projectStructure = await this.getProjectStructureAsync(args.projectPath); // Extract project name from project.godot file let projectName = basename(args.projectPath); try { const fs = require('fs'); const projectFileContent = fs.readFileSync(projectFile, 'utf8'); const configNameMatch = projectFileContent.match(/config\/name="([^"]+)"/); if (configNameMatch && configNameMatch[1]) { projectName = configNameMatch[1]; this.logDebug(`Found project name in config: ${projectName}`); } } catch (error) { this.logDebug(`Error reading project file: ${error}`); // Continue with default project name if extraction fails } return { content: [ { type: 'text', text: JSON.stringify( { name: projectName, path: args.projectPath, godotVersion: stdout.trim(), structure: projectStructure, }, null, 2 ), }, ], }; } catch (error: any) { return this.createErrorResponse( `Failed to get project info: ${error?.message || 'Unknown error'}`, [ 'Ensure Godot is installed correctly', 'Check if the GODOT_PATH environment variable is set correctly', 'Verify the project path is accessible', ] ); } }
• src/index.ts:747-758 (schema)

  Input schema definition for the get_project_info tool, specifying the required projectPath parameter.
  name: 'get_project_info', description: 'Retrieve metadata about a Godot project', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, }, required: ['projectPath'], },
• src/index.ts:946-947 (registration)

  Registration of the get_project_info tool handler in the CallToolRequestSchema switch statement.
  case 'get_project_info': return await this.handleGetProjectInfo(request.params.arguments);
• src/index.ts:667-928 (registration)

  Tool list registration in ListToolsRequestSchema handler, including get_project_info with its schema for tool discovery.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: 'launch_editor', description: 'Launch Godot editor for a specific project', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, }, required: ['projectPath'], }, }, { name: 'run_project', description: 'Run the Godot project and capture output', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scene: { type: 'string', description: 'Optional: Specific scene to run', }, }, required: ['projectPath'], }, }, { name: 'get_debug_output', description: 'Get the current debug output and errors', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'stop_project', description: 'Stop the currently running Godot project', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'get_godot_version', description: 'Get the installed Godot version', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'list_projects', description: 'List Godot projects in a directory', inputSchema: { type: 'object', properties: { directory: { type: 'string', description: 'Directory to search for Godot projects', }, recursive: { type: 'boolean', description: 'Whether to search recursively (default: false)', }, }, required: ['directory'], }, }, { name: 'get_project_info', description: 'Retrieve metadata about a Godot project', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, }, required: ['projectPath'], }, }, { name: 'create_scene', description: 'Create a new Godot scene file', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scenePath: { type: 'string', description: 'Path where the scene file will be saved (relative to project)', }, rootNodeType: { type: 'string', description: 'Type of the root node (e.g., Node2D, Node3D)', default: 'Node2D', }, }, required: ['projectPath', 'scenePath'], }, }, { name: 'add_node', description: 'Add a node to an existing scene', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scenePath: { type: 'string', description: 'Path to the scene file (relative to project)', }, parentNodePath: { type: 'string', description: 'Path to the parent node (e.g., "root" or "root/Player")', default: 'root', }, nodeType: { type: 'string', description: 'Type of node to add (e.g., Sprite2D, CollisionShape2D)', }, nodeName: { type: 'string', description: 'Name for the new node', }, properties: { type: 'object', description: 'Optional properties to set on the node', }, }, required: ['projectPath', 'scenePath', 'nodeType', 'nodeName'], }, }, { name: 'load_sprite', description: 'Load a sprite into a Sprite2D node', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scenePath: { type: 'string', description: 'Path to the scene file (relative to project)', }, nodePath: { type: 'string', description: 'Path to the Sprite2D node (e.g., "root/Player/Sprite2D")', }, texturePath: { type: 'string', description: 'Path to the texture file (relative to project)', }, }, required: ['projectPath', 'scenePath', 'nodePath', 'texturePath'], }, }, { name: 'export_mesh_library', description: 'Export a scene as a MeshLibrary resource', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scenePath: { type: 'string', description: 'Path to the scene file (.tscn) to export', }, outputPath: { type: 'string', description: 'Path where the mesh library (.res) will be saved', }, meshItemNames: { type: 'array', items: { type: 'string', }, description: 'Optional: Names of specific mesh items to include (defaults to all)', }, }, required: ['projectPath', 'scenePath', 'outputPath'], }, }, { name: 'save_scene', description: 'Save changes to a scene file', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, scenePath: { type: 'string', description: 'Path to the scene file (relative to project)', }, newPath: { type: 'string', description: 'Optional: New path to save the scene to (for creating variants)', }, }, required: ['projectPath', 'scenePath'], }, }, { name: 'get_uid', description: 'Get the UID for a specific file in a Godot project (for Godot 4.4+)', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, filePath: { type: 'string', description: 'Path to the file (relative to project) for which to get the UID', }, }, required: ['projectPath', 'filePath'], }, }, { name: 'update_project_uids', description: 'Update UID references in a Godot project by resaving resources (for Godot 4.4+)', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, }, required: ['projectPath'], }, }, ], }));
• src/index.ts:1322-1377 (helper)

  Helper function getProjectStructureAsync used by the handler to recursively scan and count scenes, scripts, assets, and other files in the project.
  private getProjectStructureAsync(projectPath: string): Promise<any> { return new Promise((resolve) => { try { const structure = { scenes: 0, scripts: 0, assets: 0, other: 0, }; const scanDirectory = (currentPath: string) => { const entries = readdirSync(currentPath, { withFileTypes: true }); for (const entry of entries) { const entryPath = join(currentPath, entry.name); // Skip hidden files and directories if (entry.name.startsWith('.')) { continue; } if (entry.isDirectory()) { // Recursively scan subdirectories scanDirectory(entryPath); } else if (entry.isFile()) { // Count file by extension const ext = entry.name.split('.').pop()?.toLowerCase(); if (ext === 'tscn') { structure.scenes++; } else if (ext === 'gd' || ext === 'gdscript' || ext === 'cs') { structure.scripts++; } else if (['png', 'jpg', 'jpeg', 'webp', 'svg', 'ttf', 'wav', 'mp3', 'ogg'].includes(ext || '')) { structure.assets++; } else { structure.other++; } } } }; // Start scanning from the project root scanDirectory(projectPath); resolve(structure); } catch (error) { this.logDebug(`Error getting project structure asynchronously: ${error}`); resolve({ error: 'Failed to get project structure', scenes: 0, scripts: 0, assets: 0, other: 0 }); } }); }