Skip to content

README.md

Latest commit

 

History

History
200 lines (151 loc) · 6.28 KB

README.md

File metadata and controls

200 lines (151 loc) · 6.28 KB
Raw

Google Analytics MCP Server (Experimental)

This repo contains the source code for running a local MCP server that interacts with APIs for Google Analytics.

Tools 🛠️

The server uses the Google Analytics Admin API and Google Analytics Data API to provide several Tools for use with LLMs.

Retrieve account and property information 🟠

  • get_account_summaries: Retrieves information about the user's Google Analytics accounts and properties.
  • get_property_details: Returns details about a property.
  • list_google_ads_links: Returns a list of links to Google Ads accounts for a property.

Run core reports 📙

  • run_report: Run a Google Analytics report using the Data API.
  • get_dimensions: Retrieves Core Reporting Dimensions for a specific property, including its custom dimensions.
  • get_metrics: Retrieves Core Reporting Metrics for a specific property, including its custom dimensions.
  • get_standard_dimensions: Returns a list of standard dimensions.
  • get_standard_metrics: Returns a list of standard metrics.
  • run_report_date_ranges_hints: Provides hints about the expected values for the date_ranges argument for the run_report tool.
  • run_report_metric_filter_hints: Provides hints about the expected values for the metric_filter argument for the run_report and run_realtime_report tools.
  • run_report_dimension_filter_hints: Provides hints about the expected values for the dimension_filter argument for the run_report and run_realtime_report tools.

Run realtime reports ⏳

  • run_realtime_report: Run a Google Analytics realtime report using the Data API.
  • get_realtime_dimensions: Retrieves the list of realtime reporting dimensions.
  • get_realtime_metrics: Retrieves the list of realtime metrics.

Setup instructions

Setup involves the following steps:

  1. Configure Python.
  2. Configure credentials for Google Analytics.
  3. Configure Gemini.

Configure Python 🐍

Install pipx.

Enable APIs in your project ✅

Follow the instructions to enable the following APIs in your Google Cloud project:

Configure credentials 🔑

Configure your Application Default Credentials (ADC). Make sure the credentials are for a user with access to your Google Analytics accounts or properties.

Credentials must include the Google Analytics read-only scope:

https://www.googleapis.com/auth/analytics.readonly

Check out Manage OAuth Clients for how to create an OAuth client.

Here are some sample gcloud commands you might find useful:

  • Set up ADC using user credentials and an OAuth desktop or web client after downloading the client JSON to YOUR_CLIENT_JSON_FILE.

    gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

  • Set up ADC using service account impersonation.

    gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

Configure Gemini

  1. Install Gemini CLI or Gemini Code Assist

  2. Create or edit the file at ~/.gemini/settings.json, adding your server to the mcpServers list.

    {
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleanalytics/google-analytics-mcp.git",
        "google-analytics-mcp"
      ]
    }
  }
}

  3. Optional: Configure the GOOGLE_APPLICATION_CREDENTIALS environment variable in Gemini settings. You may want to do this if you always want to use a specific set of credentials, regardless of which Application Default Credentials are selected in your current environment.

    In ~/.gemini/settings.json, add a GOOGLE_APPLICATION_CREDENTIALS attribute to the env object. Replace PATH_TO_ADC_JSON in the following example with the full path to the ADC JSON file you always want to use for your MCP server.

    {
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleanalytics/google-analytics-mcp.git",
        "google-analytics-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_ADC_JSON"
      }
    }
  }
}

Try it out 🥼

Launch Gemini Code Assist or Gemini CLI and type /mcp. You should see analytics-mcp listed in the results.

Here are some sample prompts to get you started:

  • Ask what the server can do:

    what can the analytics-mcp server do?

  • Ask about a Google Analytics property

    Give me details about my Google Analytics property with 'xyz' in the name

  • Prompt for analysis:

    what are the most popular events in my Google Analytics property in the last 180 days?

  • Ask about signed-in users:

    were most of my users in the last 6 months logged in?

  • Ask about property configuration:

    what are the custom dimensions and custom metrics in my property?

Contributing

Contributions welcome! See the Contributing Guide.