naihaoko/ga4-mcp-server

GA4 MCP Server

This project sets up a Model Context Protocol (MCP) server that connects to Google Analytics 4 (GA4) using the @modelcontextprotocol/sdk and the @google-analytics/data library. It exposes several GA4 analytics tools to be used with applications like Claude Desktop.

Setup

1. Clone the repository:

   git clone <repository-url>
   cd ga4-mcp-server
   

2. Install dependencies:

   If package.json does not exist, initialize it first:

   npm init -y
   

   Then, install the project's dependencies:

   npm install @modelcontextprotocol/sdk @google-analytics/data dotenv
   

   This command installs all necessary project dependencies, including the MCP SDK, Google Analytics Data library, and dotenv for environment variable management.

3. Google Service Account Key:

   To authenticate with the Google Analytics Data API, you need a Google service account key. Follow these steps to obtain one:

   • Create a Service Account:
     1. Go to the Google Cloud Console.
     2. Navigate to "IAM & Admin" > "Service Accounts".
     3. Click "Create Service Account".
     4. Provide a name for the service account and an optional description.
     5. Click "Done".
   • Grant Permissions:
     1. After creating the service account, you'll need to grant it the necessary permissions to access your Google Analytics 4 data.
     2. On the "Grant this service account access to project" step (or by editing the service account later), add the role "Analytics Viewer" to the service account. This role grants read-only access to Google Analytics data.
     3. Click "Done".
   • Generate JSON Key:
     1. In the "Service Accounts" page, click on the newly created service account.
     2. Go to the "Keys" tab.
     3. Click "Add Key" > "Create new key".
     4. Select "JSON" as the key type and click "Create".
     5. A JSON file containing your service account key will be downloaded to your computer.
   • Save the Key File: Place the downloaded JSON key file in the project root of this repository. Rename the file to service-account-key.json (or update the .env file accordingly if you choose a different name).

4. Environment Variables:

   Create a .env file in the project root with the following content:

   GOOGLE_APPLICATION_CREDENTIALS="./service-account-key.json"
   GA_PROPERTY_ID="YOUR_GA_PROPERTY_ID"
   

   Replace "YOUR_GA_PROPERTY_ID" with your actual Google Analytics 4 Property ID.

   How to find your GA4 Property ID:

   1. Go to your Google Analytics account.
   2. Select the desired GA4 property.
   3. Navigate to "Admin" (the gear icon at the bottom left).
   4. In the "Property" column, click on "Property settings".
   5. Your GA4 Property ID will be displayed there (it's a numeric ID, e.g., 123456789).

5. Configure MCP-compatible applications (e.g., Claude Desktop, Gemini CLI):

   To integrate this MCP server with your preferred MCP-compatible application, you will need to add a configuration snippet to its settings file. The location and name of this file may vary (e.g., claude_desktop_config.json for Claude Desktop, or ~/.gemini/settings.json for Gemini CLI).

   For more information on installing and using Gemini CLI, refer to its GitHub repository: https://github.com/google-gemini/gemini-cli

   For Claude Desktop, go to: https://claude.ai/download

   Locate your application's settings file and add the following JSON snippet under the mcpServers key. If the mcpServers key does not exist, you may need to create it.

   {
     "mcpServers": {
       "ga4-analytics": {
         "name": "google_analytics",
         "command": "node",
         "args": ["<PATH_TO_YOUR_REPO>/src/index.js"],
         "cwd": "<PATH_TO_YOUR_REPO>",
         "env": {
           "GOOGLE_APPLICATION_CREDENTIALS": "<PATH_TO_YOUR_REPO>/service-account-key.json",
           "GA_PROPERTY_ID": "YOUR_GA_PROPERTY_ID"
         }
       }
     }
   }
   

   Important: Replace <PATH_TO_YOUR_REPO> with the absolute path to your ga4-mcp-server directory on your local machine.

Running the Server

To run the MCP server, execute the following command in your terminal:

node src/index.js

For background execution, you can use:

node src/index.js &

Start Asking GA4 Questions

After adding the configuration and running the MCP server, restart your MCP-compatible application (e.g., Claude Desktop, Gemini CLI) for the changes to take effect. You can then start using the GA4 MCP tools within your application.

Available Tools

This server exposes the following Google Analytics 4 tools, allowing you to retrieve various types of data from your GA4 property through the MCP interface:

Contributing

Feel free to fork this repository and contribute to its development.