Google Analytics MCP Server (Experimental)

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

Join the discussion and ask questions in the 🤖-analytics-mcp channel on Discord.

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

• get_account_summaries: Retrieves information about the user's Google Analytics accounts and properties.
• get_account: Returns details about an account.
• list_accounts: Lists all accounts accessible to the caller.
• get_property_details: Returns details about a property.
• list_properties: Lists all properties accessible to the caller.
• list_google_ads_links: Returns a list of links to Google Ads accounts for a property.
• list_property_annotations: Returns annotations for a property.
• get_data_sharing_settings: Returns the data sharing settings for an account.
• get_data_retention_settings: Returns the data retention settings for a property.
• search_change_history_events: Searches an account or property change history.
• run_access_report: Runs an access report for a property or account.

These write tools require the analytics.edit scope. See Configure credentials.

• provision_account_ticket: Requests a ticket for creating a new account.
• update_account: Updates an account.
• delete_account: Soft-deletes an account.
• acknowledge_user_data_collection: Acknowledges user data collection terms for a property.
• create_property: Creates a property.
• update_property: Updates a property.
• delete_property: Soft-deletes a property.
• update_data_retention_settings: Updates the data retention settings for a property.

• get_data_stream: Returns details about a data stream.
• list_data_streams: Lists the data streams for a property.
• create_data_stream: Creates a data stream.
• update_data_stream: Updates a data stream.
• delete_data_stream: Deletes a data stream.
• get_measurement_protocol_secret: Returns details about a measurement protocol secret.
• list_measurement_protocol_secrets: Lists the measurement protocol secrets for a data stream.
• create_measurement_protocol_secret: Creates a measurement protocol secret.
• update_measurement_protocol_secret: Updates a measurement protocol secret.
• delete_measurement_protocol_secret: Deletes a measurement protocol secret.

• get_custom_dimension: Returns details about a custom dimension.
• list_custom_dimensions: Lists the custom dimensions for a property.
• create_custom_dimension: Creates a custom dimension.
• update_custom_dimension: Updates a custom dimension.
• archive_custom_dimension: Archives a custom dimension.
• get_custom_metric: Returns details about a custom metric.
• list_custom_metrics: Lists the custom metrics for a property.
• create_custom_metric: Creates a custom metric.
• update_custom_metric: Updates a custom metric.
• archive_custom_metric: Archives a custom metric.

• get_key_event: Returns details about a key event.
• list_key_events: Lists the key events for a property.
• create_key_event: Creates a key event.
• update_key_event: Updates a key event.
• delete_key_event: Deletes a key event.
• get_conversion_event: Returns details about a conversion event (deprecated).
• list_conversion_events: Lists the conversion events for a property (deprecated).
• create_conversion_event: Creates a conversion event (deprecated).
• update_conversion_event: Updates a conversion event (deprecated).
• delete_conversion_event: Deletes a conversion event (deprecated).

• list_firebase_links: Lists the Firebase links for a property.
• create_firebase_link: Creates a Firebase link.
• delete_firebase_link: Deletes a Firebase link.
• create_google_ads_link: Creates a Google Ads link.
• update_google_ads_link: Updates a Google Ads link.
• delete_google_ads_link: Deletes a Google Ads link.

• run_report: Runs a Google Analytics report using the Data API.
• run_funnel_report: Runs a Google Analytics funnel report using the Data API.
• get_custom_dimensions_and_metrics: Retrieves the custom dimensions and metrics for a specific property.

• run_realtime_report: Runs a Google Analytics realtime report using the Data API.

✨ Watch the Google Analytics MCP Setup Tutorial on YouTube for a step-by-step walkthrough of these instructions.

Setup involves the following steps:

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

Install pipx.

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

• Google Analytics Admin API
• Google Analytics Data API

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. To use the admin write tools (create, update, delete, archive), credentials must also include the edit scope:

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

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/analytics.edit,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/analytics.edit,https://www.googleapis.com/auth/cloud-platform

When the gcloud auth application-default command completes, copy the PATH_TO_CREDENTIALS_JSON file location printed to the console in the following message. You'll need this for the next step!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Google now blocks the gcloud default OAuth client from granting the restricted analytics.edit scope. Symptom: read-only tools work, but admin write tools fail with 403 ACCESS_TOKEN_SCOPE_INSUFFICIENT. The token comes back with only analytics.readonly + cloud-platform (check with tokeninfo after a fresh refresh).

Fix — create your own Desktop OAuth client in Cloud Console (keep the app in Testing mode and add your Google account as a test user), download its client_secret.json, then:

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

The OAuth consent screen must be in Testing mode with your account added as a test user — otherwise the restricted analytics.edit scope is blocked.

After re-running the login, restart the MCP server — analytics-mcp caches credentials at process start, so a running session still holds the old (read-only) token until restarted. To verify write access before restarting, call the Admin API directly from the project venv:

.venv/bin/python -c "\
import google.auth; from google.analytics import admin_v1beta; \
from google.auth.transport.requests import Request; \
c,_=google.auth.default(scopes=['https://www.googleapis.com/auth/analytics.edit']); c.refresh(Request()); \
print(admin_v1beta.AnalyticsAdminServiceClient(credentials=c).create_key_event(\
  parent='properties/<PROPERTY_ID>', key_event=admin_v1beta.KeyEvent(event_name='onboarding')).name)"

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.

   Replace PATH_TO_CREDENTIALS_JSON with the path you copied in the previous step.

   We also recommend that you add a GOOGLE_CLOUD_PROJECT attribute to the env object. Replace YOUR_PROJECT_ID in the following example with the project ID of your Google Cloud project.

   {
     "mcpServers": {
       "analytics-mcp": {
         "command": "pipx",
         "args": ["run", "analytics-mcp"],
         "env": {
           "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
           "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"
         }
       }
     }
   }

1. Add the MCP server with the following command:

   Replace PATH_TO_CREDENTIALS_JSON with the path you copied in the previous step, and replace YOUR_PROJECT_ID with the project ID of your Google Cloud project.

   claude mcp add analytics-mcp \
     --scope user \
     -e "GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIALS_JSON" \
     -e "GOOGLE_PROJECT_ID=YOUR_PROJECT_ID" \
     -- pipx run analytics-mcp

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?
  

Contributions welcome! See the Contributing Guide.