Godot MCP Server

Instructions

Implementation Reference

• src/tools/scene-tools.ts:127-134 (handler)

  The handler function that executes the godot_add_node tool. It extracts parameters, makes a POST request to the Godot client at '/scene/node', and returns the created node information.

  async ({ parent_path, node_type, node_name, scene_path, properties }) => {
    const result = await godotRequest<GodotNodeInfo>("POST", "/scene/node", {
      parent_path, node_type, node_name, scene_path, properties
    });
    return {
      content: [{ type: "text", text: `Node created: ${JSON.stringify(result, null, 2)}` }]
    };
  }

• src/tools/scene-tools.ts:118-124 (schema)

  The input validation schema using Zod for godot_add_node. Defines required fields (parent_path, node_type, node_name) and optional fields (scene_path, properties).

  inputSchema: z.object({
    parent_path: z.string().describe("Node path of the parent node"),
    node_type: z.string().describe("Godot class name for the new node"),
    node_name: z.string().describe("Name for the new node"),
    scene_path: z.string().optional().describe("Scene to modify. Omit for active scene."),
    properties: z.record(z.unknown()).optional().describe("Initial property key/value pairs")
  }).strict(),

• src/tools/scene-tools.ts:99-135 (registration)

  The complete registration of the godot_add_node tool with MCP server, including title, description, input schema, annotations, and the handler function.

    server.registerTool(
      "godot_add_node",
      {
        title: "Add Node to Scene",
        description: `Adds a new node of the specified type as a child of the given parent node.
  
  Args:
    - parent_path (string): Node path of the parent e.g. "/root/Main"
    - node_type (string): Godot class name e.g. "Sprite2D", "CharacterBody2D", "Label", "AudioStreamPlayer"
    - node_name (string): Name for the new node
    - scene_path (string, optional): Scene to modify. Defaults to active scene.
    - properties (object, optional): Initial property values to set on the new node.
  
  Returns:
    { name, type, path } of the created node.
  
  Examples:
    - Use when: "Add a Sprite2D called PlayerSprite under /root/Main"
    - Use when: "Add a Label node to the HUD with text 'Score: 0'"`,
        inputSchema: z.object({
          parent_path: z.string().describe("Node path of the parent node"),
          node_type: z.string().describe("Godot class name for the new node"),
          node_name: z.string().describe("Name for the new node"),
          scene_path: z.string().optional().describe("Scene to modify. Omit for active scene."),
          properties: z.record(z.unknown()).optional().describe("Initial property key/value pairs")
        }).strict(),
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
      },
      async ({ parent_path, node_type, node_name, scene_path, properties }) => {
        const result = await godotRequest<GodotNodeInfo>("POST", "/scene/node", {
          parent_path, node_type, node_name, scene_path, properties
        });
        return {
          content: [{ type: "text", text: `Node 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. Handles errors, connection issues, and response parsing.

  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;
    }
  }