MCP Server for Google Analytics 4 (Node.js/TypeScript) - v0.1.0

A Model Context Protocol (MCP) server, built with Node.js and TypeScript, that allows Large Language Models (LLMs) to interact with Google Analytics 4 (GA4) data using the Google Analytics Data API.

This server is designed to be invoked by an MCP controller (like bdmarvin1/typingmind-mcp) which handles the OAuth 2.0 flow and passes an access token for API authentication.

Features

• Provides MCP tools to:
  • Run standard GA4 reports (run_report)
  • Run realtime GA4 reports (run_realtime_report)
  • Get GA4 metadata for dimensions and metrics (get_metadata)
• Authenticates to Google Analytics Data API using OAuth 2.0 access tokens provided by the calling MCP controller.
• Built with TypeScript for type safety.
• Uses Zod for robust validation of tool parameters.
• Packaged for NPM and runnable via npx.

Prerequisites

• Node.js (LTS version, e.g., v18 or v20, as per package.json engines if specified)
• npm (or yarn/pnpm)

Installation (for an MCP Controller or Standalone Use)

Once published to NPM under bdmarvin1-mcp-server-ga4-node (or your chosen package name):

npm install -g bdmarvin1-mcp-server-ga4-node

This will make the bdmarvin1-mcp-server-ga4-node command globally available (note: the command name in package.json's bin field is bdmarvin1-mcp-server-ga4-node).

Alternatively, it can be run directly using npx without global installation (see Usage).

Authentication

This server relies entirely on a Google OAuth 2.0 access token being passed to its tool methods by the calling MCP controller.

• The MCP controller (e.g., bdmarvin1/typingmind-mcp) is responsible for:
  1. Performing the full OAuth 2.0 authorization code flow (or client credentials flow if applicable).
  2. Obtaining an access token with the necessary Google Analytics Data API scopes (typically https://www.googleapis.com/auth/analytics.readonly).
  3. Refreshing the access token when it expires.
• When calling a tool on this server, the controller must inject the valid access token into the arguments object under the key __google_access_token__.

  // Example of 'arguments' object from controller:
  {
    "__google_access_token__": "USER_PROVIDED_ACCESS_TOKEN",
    "property_id": "123456789",
    "metrics": ["sessions"]
    // ... other tool-specific arguments
  }

• This server does not implement any ADC (Application Default Credentials) fallback for API calls, as it's designed to be used in an OAuth-managed environment.

Usage

Intended Usage (with an MCP Controller like typingmind-mcp)

1. Publish this package to NPM. (e.g., as bdmarvin1-mcp-server-ga4-node)
2. Configure your typingmind-mcp controller to launch this server. The configuration in typingmind-mcp would look something like this:

   {
       "mcpServers": {
           "ga4-node-service": { // Unique ID for this server instance
               "command": "npx",
               "args": [
                   "bdmarvin1-mcp-server-ga4-node", // The npm package name
                   "--",                            // Separator for script arguments
                   "--transport", "stdio"
                   // No need to pass --property-id here if your tools always require it
                   // or if GA4_PROPERTY_ID env var is set for the npx execution environment
               ]
           }
       }
   }

   typingmind-mcp will then handle spawning this server via npx and communicating with it over STDIO when its tools are invoked.

Direct Execution (for local testing/development)

After building the project (npm run build), you can run it locally:

1. Using the start script (recommended for local testing):

   npm start 

   This runs node dist/main.js --transport stdio. The server will then listen on STDIN for JSON-RPC requests.

2. Using npx with the local build: Make sure you have built the project first (npm run build).

   npx . --transport stdio 

   (The . tells npx to run the binary defined in the current local package's package.json).

3. Globally installed command (after npm install -g . or npm install -g bdmarvin1-mcp-server-ga4-node):

   bdmarvin1-mcp-server-ga4-node --transport stdio

Command-line arguments for the server:

• --transport stdio: (Required) Tells the server to use STDIO for MCP communication.
• --dump-schema: Prints the JSON schema for all tools and exits. Useful for generating manifests.

  node dist/main.js --dump-schema > ga4-node-mcp-schema.json

Available Tools

The server exposes the following tools. An access token with analytics.readonly scope is required.

run_report

Runs a standard GA4 report.

• Parameters (defined in src/schemas.ts using Zod):
  • property_id: string (e.g., "123456789") - Required.
  • metrics: string[] (e.g., ["activeUsers", "sessions"]) - Required, min 1.
  • dimensions?: string[] (e.g., ["date", "country"]) - Optional.
  • date_range?: string | { start_date: string, end_date: string } (e.g., "last7days" or {"start_date": "2023-01-01", "end_date": "2023-01-31"}) - Optional, defaults to "last30days". Dates must be YYYY-MM-DD.
  • limit?: number (e.g., 100) - Optional, positive integer, defaults to 10.
  • dimensionFilter?: FilterExpression (See GA4 API docs for FilterExpression structure) - Optional.
  • metricFilter?: FilterExpression - Optional.
  • orderBys?: OrderBy[] (See GA4 API docs for OrderBy structure) - Optional.
  • currencyCode?: string (e.g., "USD") - Optional.
  • keepEmptyRows?: boolean (e.g., true) - Optional, defaults to false.
  • returnPropertyQuota?: boolean - Optional.
• Internal Argument (from controller): __google_access_token__: string - Required.

run_realtime_report

Gets real-time data for the past 30 minutes.

• Parameters:
  • property_id: string - Required.
  • metrics: string[] - Required, min 1.
  • dimensions?: string[] - Optional.
  • limit?: number - Optional, default 10.
  • dimensionFilter?: FilterExpression - Optional.
  • metricFilter?: FilterExpression - Optional.
  • orderBys?: OrderBy[] - Optional.
  • returnPropertyQuota?: boolean - Optional.
• Internal Argument (from controller): __google_access_token__: string - Required.

get_metadata

Retrieves available metrics and dimensions for a GA4 property.

• Parameters:
  • property_id: string - Required.
  • type?: "metrics" | "dimensions" | "all" - Optional, defaults to "all".
• Internal Argument (from controller): __google_access_token__: string - Required.

Development

1. Clone the repository: git clone https://github.com/bdmarvin1/mcp-server-ga4-node.git
2. Navigate into the project directory: cd mcp-server-ga4-node
3. Install dependencies:

   npm install

4. Build the TypeScript:

   npm run build

5. Run in development mode (watches for changes and rebuilds/restarts):

   npm run dev

   This uses concurrently and nodemon. The server will listen on STDIO.

Testing Manually with STDIO

1. Start the server: npm start (or npm run dev and wait for it to start).

2. In the same terminal, paste a single-line JSON-RPC request and press Enter.

   Example tools/list:

   {"jsonrpc":"2.0","method":"tools/list","id":1}

   Example tools/call for run_report:

   {"jsonrpc":"2.0","method":"tools/call","params":{"name":"run_report","arguments":{"__google_access_token__":"YOUR_ACCESS_TOKEN","property_id":"YOUR_PROPERTY_ID","metrics":["activeUsers"]}},"id":2}

License

MIT