Godot MCP Server

Instructions

Implementation Reference

• src/tools/asset-tools.ts:117-147 (handler)

  Main implementation of godot_create_scene tool - includes registration with schema definition and the handler function that creates a new scene file by calling the Godot API via godotRequest with POST /scenes/create

    server.registerTool(
      "godot_create_scene",
      {
        title: "Create New Scene File",
        description: `Creates a new empty scene file (.tscn) with a specified root node type.
  
  Args:
    - scene_path (string): res:// path for the new scene e.g. "res://levels/level2.tscn"
    - root_type (string): Godot class for the root node e.g. "Node2D", "Node3D", "Control", "CharacterBody2D"
    - root_name (string, optional): Name for the root node (defaults to the scene file stem)
    - open_in_editor (boolean, optional): Open the new scene in the editor (default: true)
  
  Returns:
    { path, root_node, root_type } of the created scene.`,
        inputSchema: z.object({
          scene_path: z.string().describe("res:// destination path for the new .tscn"),
          root_type: z.string().describe("Godot class name for the root node"),
          root_name: z.string().optional().describe("Name for the root node"),
          open_in_editor: z.boolean().default(true).describe("Open in editor after creation")
        }).strict(),
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
      },
      async ({ scene_path, root_type, root_name, open_in_editor }) => {
        const result = await godotRequest<{ path: string; root_node: string; root_type: string }>(
          "POST", "/scenes/create", { scene_path, root_type, root_name, open_in_editor }
        );
        return {
          content: [{ type: "text", text: `Scene created: ${JSON.stringify(result, null, 2)}` }]
        };
      }
    );

• src/services/godot-client.ts:11-43 (helper)

  The godotRequest helper function used by the handler to make HTTP requests to the Godot MCP Bridge API endpoint /scenes/create

  export async function godotRequest<T>(
    method: "GET" | "POST" | "PUT" | "DELETE",
    path: string,
    body?: unknown
  ): Promise<T> {
    try {
      const response = await client.request<ApiResponse<T>>({
        method,
        url: path,
        data: body
      });
  
      const payload = response.data;
      if (!payload.success) {
        throw new Error(payload.error ?? "Godot returned an unsuccessful response.");
      }
      return payload.data as T;
    } catch (err) {
      if (axios.isAxiosError(err)) {
        const axErr = err as AxiosError<ApiResponse<unknown>>;
        if (axErr.code === "ECONNREFUSED") {
          throw new Error(
            `Cannot connect to Godot at ${GODOT_BASE_URL}. ` +
            `Make sure the MCP Bridge plugin is enabled and the project is running ` +
            `(Project > Tools > MCP Bridge > Start Server).`
          );
        }
        const serverMsg = axErr.response?.data?.error;
        throw new Error(serverMsg ?? axErr.message);
      }
      throw err;
    }
  }

• src/tools/asset-tools.ts:131-136 (schema)

  Input schema definition using zod - validates scene_path (required), root_type (required), root_name (optional), and open_in_editor (optional, default: true)

  inputSchema: z.object({
    scene_path: z.string().describe("res:// destination path for the new .tscn"),
    root_type: z.string().describe("Godot class name for the root node"),
    root_name: z.string().optional().describe("Name for the root node"),
    open_in_editor: z.boolean().default(true).describe("Open in editor after creation")
  }).strict(),

• dist/tools/asset-tools.js:92-116 (handler)

  Compiled JavaScript version of the godot_create_scene tool implementation with the same registration and handler logic

      server.registerTool("godot_create_scene", {
          title: "Create New Scene File",
          description: `Creates a new empty scene file (.tscn) with a specified root node type.
  
  Args:
    - scene_path (string): res:// path for the new scene e.g. "res://levels/level2.tscn"
    - root_type (string): Godot class for the root node e.g. "Node2D", "Node3D", "Control", "CharacterBody2D"
    - root_name (string, optional): Name for the root node (defaults to the scene file stem)
    - open_in_editor (boolean, optional): Open the new scene in the editor (default: true)
  
  Returns:
    { path, root_node, root_type } of the created scene.`,
          inputSchema: z.object({
              scene_path: z.string().describe("res:// destination path for the new .tscn"),
              root_type: z.string().describe("Godot class name for the root node"),
              root_name: z.string().optional().describe("Name for the root node"),
              open_in_editor: z.boolean().default(true).describe("Open in editor after creation")
          }).strict(),
          annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
      }, async ({ scene_path, root_type, root_name, open_in_editor }) => {
          const result = await godotRequest("POST", "/scenes/create", { scene_path, root_type, root_name, open_in_editor });
          return {
              content: [{ type: "text", text: `Scene created: ${JSON.stringify(result, null, 2)}` }]
          };
      });

• src/index.ts:6-16 (registration)

  Top-level registration that imports and calls registerAssetTools(server) to register the godot_create_scene tool along with other asset management tools

  import { registerAssetTools } from "./tools/asset-tools.js";
  import { GODOT_BASE_URL } from "./constants.js";
  
  const server = new McpServer({
    name: "godot-mcp-server",
    version: "1.0.0"
  });
  
  registerSceneTools(server);
  registerScriptTools(server);
  registerAssetTools(server);