Analytics

Google Analytics MCP Server

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.

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.
• list_property_annotations: Returns annotations for a property.
• create_property_annotation: Creates an annotation for a property (requires passing the --allow-write flag and the analytics.edit scope).

Run core reports 📙

• 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 reports ⏳

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

Setup instructions 🔧

✨ 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.

Configure Python 🐍

Install pipx.

Enable APIs in your project ✅

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

• Google Analytics Admin API
• Google Analytics Data API

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

If you plan to enable write tools (such as create_property_annotation) using the --allow-write flag, your credentials must also include the edit scope:

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/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
  

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]

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.

   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_CLOUD_PROJECT": "YOUR_PROJECT_ID"
         }
       }
     }
   }
   

   To enable write tools (e.g. create_property_annotation), append "--allow-write" to "args": ["run", "analytics-mcp", "--allow-write"].

Configure Claude Code

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_CLOUD_PROJECT=YOUR_PROJECT_ID" \
     -- pipx run analytics-mcp
   

Multi-tenant HTTP & End-User OAuth 🌐

To host analytics-mcp as a shared multi-tenant HTTP service (where each end user signs in with their own Google account via OAuth 2.0 rather than using server-side Application Default Credentials), start the server with --transport http:

pipx run analytics-mcp \
  --transport http --stateless-http --host 0.0.0.0 --port 8080

• Agent Framework OAuth (e.g. Google ADK): Configure per-user Google OAuth on McpToolset so end users are automatically prompted with a Sign in button in the chat UI, and can even combine Google Analytics MCP alongside other MCP servers in the same agent. Paired with --stateless-http, this mode is completely stateless and horizontally scalable across multiple replicas.

• Native MCP OAuth 2.1 Server (--oauth): Pass --oauth (with GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, and optional ANALYTICS_MCP_ISSUER_URL set) to enable the built-in MCP OAuth 2.1 Authorization Server:

  export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
  export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
  export ANALYTICS_MCP_ISSUER_URL="https://analytics-mcp.yourdomain.com"
  
  pipx run analytics-mcp \
    --transport http --stateless-http --oauth --host 0.0.0.0 --port 8080
  

  Note: The built-in --oauth provider stores dynamic client registrations, pending authorization state, and refresh tokens in process memory (run as a single instance or with sticky sessions; restarts require re-authentication).

See the complete walkthrough, Dockerfile, and runnable agent code in examples/multi_tenant_adk_agent/README.md.

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.

Troubleshooting

See the Troubleshooting Guide for common issues and workarounds.