Godot MCP Server

Instructions

Implementation Reference

• src/tools/asset-tools.ts:103-113 (handler)

  The handler function that executes the godot_assign_resource tool logic. It makes a POST request to the Godot server at '/filesystem/assign-resource' with the node_path, property, resource_path, and optional scene_path, then returns a confirmation message.

  async ({ node_path, property, resource_path, scene_path }) => {
    await godotRequest<void>("POST", "/filesystem/assign-resource", {
      node_path, property, resource_path, scene_path
    });
    return {
      content: [{
        type: "text",
        text: `Assigned ${resource_path} to ${node_path}.${property}`
      }]
    };
  }

• src/tools/asset-tools.ts:75-102 (registration)

  Tool registration for godot_assign_resource with title, description, input schema (using Zod for validation), and annotations defining it as idempotent and non-destructive.

    server.registerTool(
      "godot_assign_resource",
      {
        title: "Assign Resource to Node Property",
        description: `Loads a resource and assigns it to a property of a node. 
  Useful for setting textures, materials, audio streams, etc.
  
  Args:
    - node_path (string): Node path e.g. "/root/Main/Player/Sprite2D"
    - property (string): Property name e.g. "texture", "material", "stream"
    - resource_path (string): res:// path to the resource to assign
    - scene_path (string, optional): Scene to modify. Defaults to active scene.
  
  Returns:
    Confirmation of the assignment.
  
  Examples:
    - Use when: "Set the player sprite texture to res://assets/player.png"
      -> node_path: "/root/Main/Player/Sprite2D", property: "texture",
         resource_path: "res://assets/player.png"`,
        inputSchema: z.object({
          node_path: z.string().describe("Target node path"),
          property: z.string().describe("Property to set the resource on"),
          resource_path: z.string().describe("res:// path to the resource"),
          scene_path: z.string().optional().describe("Scene to modify. Omit for active scene.")
        }).strict(),
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
      },

• src/tools/asset-tools.ts:95-100 (schema)

  Zod schema definition for input validation of the godot_assign_resource tool, validating node_path, property, resource_path (all required) and scene_path (optional).

  inputSchema: z.object({
    node_path: z.string().describe("Target node path"),
    property: z.string().describe("Property to set the resource on"),
    resource_path: z.string().describe("res:// path to the resource"),
    scene_path: z.string().optional().describe("Scene to modify. Omit for active scene.")
  }).strict(),

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

  The godotRequest helper function that handles HTTP communication with the Godot server. It creates an axios client with proper headers and timeout, wraps requests with error handling, and validates the success response from the API.

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