GA4 MCP Server

Instructions

Implementation Reference

• src/tools/admin.ts:100-117 (handler)

  The main handler function for ga4_property_annotations tool. It accepts a propertyId parameter and returns information about the API limitation - annotations require v1alpha API which is not fully supported in the googleapis Node.js library, so it returns a message explaining this limitation with suggestions for alternatives.

  export async function listPropertyAnnotations(propertyId: string): Promise<ToolResponse> {
    try {
      // Note: The googleapis Node.js library uses v1beta which doesn't include annotations.
      // Annotations require v1alpha which is available in the Python client.
      // For now, we'll return a message explaining this limitation.
      const propertyName = constructPropertyResourceName(propertyId);
  
      return createSuccessResponse({
        message: `Property annotations for ${propertyName} are not available through the googleapis Node.js library. ` +
          `The reportingDataAnnotations API requires the v1alpha version which is not fully supported in this library. ` +
          `To access annotations, please use the Google Analytics Admin API v1alpha directly or the Python client library.`,
        propertyId: propertyName,
        suggestedAlternative: "Use the GA4 web interface to view annotations, or implement direct REST API calls to v1alpha.",
      });
    } catch (error) {
      return createErrorResponse(`Failed to list property annotations for ${propertyId}`, error);
    }
  }

• src/tools/index.ts:69-81 (registration)

  Tool registration definition for ga4_property_annotations, including the tool name, description (explains that annotations are notes marking specific dates or periods for events like releases, campaigns, or traffic changes), and input schema requiring a propertyId string.

    name: "ga4_property_annotations",
    description: "Returns annotations for a GA4 property. Annotations are notes that mark specific dates or periods, typically used to record events like releases, campaigns, or traffic changes.",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: {
          type: "string",
          description: "The Google Analytics property ID. Accepted formats: '123456789' or 'properties/123456789'",
        },
      },
      required: ["propertyId"],
    },
  },

• src/tools/index.ts:265-266 (registration)

  Routing logic in the handleToolCall switch statement that maps the ga4_property_annotations tool name to the listPropertyAnnotations handler function, passing the propertyId argument.

  case "ga4_property_annotations":
    return await listPropertyAnnotations(args.propertyId as string);

• src/utils/helpers.ts:15-41 (helper)

  Helper function constructPropertyResourceName used by the handler to validate and format the property ID. Accepts numeric or string formats (e.g., '123456789' or 'properties/123456789') and returns the standardized format 'properties/123456789'.

  export function constructPropertyResourceName(propertyId: string | number): string {
    let propertyNum: number | null = null;
  
    if (typeof propertyId === "number") {
      propertyNum = propertyId;
    } else if (typeof propertyId === "string") {
      const trimmed = propertyId.trim();
      if (/^\d+$/.test(trimmed)) {
        propertyNum = parseInt(trimmed, 10);
      } else if (trimmed.startsWith("properties/")) {
        const numericPart = trimmed.split("/")[1];
        if (numericPart && /^\d+$/.test(numericPart)) {
          propertyNum = parseInt(numericPart, 10);
        }
      }
    }
  
    if (propertyNum === null) {
      throw new Error(
        `Invalid property ID: ${propertyId}. ` +
        "A valid property value is either a number or a string starting " +
        "with 'properties/' and followed by a number."
      );
    }
  
    return `properties/${propertyNum}`;
  }

• src/utils/helpers.ts:46-55 (helper)

  Helper function createSuccessResponse used by the handler to format the successful response as an MCP tool response with JSON data.

  export function createSuccessResponse(data: unknown): ToolResponse {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }