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), }, ], }; }