Google Analytics MCP Server — adtechnacity fork (Experimental)

This is a fork. It is based on googleanalytics/google-analytics-mcp (Apache-2.0) and maintained at adtechnacity/ga-mcp. It adds Google Analytics Admin API write tools — create_custom_dimension and create_key_event — on top of the upstream read-only server, and broadens the requested OAuth scope to include analytics.edit so those tools can run.

Everything from upstream still works unchanged. The Python package/module is still analytics_mcp and the entry point is still python -m analytics_mcp.server, so it's a drop-in replacement. This fork is not published to PyPI — run it from source (see Setup).

⚠️ The write tools make permanent property-configuration changes. Beyond the analytics.edit scope, the authenticated principal must also hold an Editor / Administrator role on the target GA4 property, or the Admin API returns PERMISSION_DENIED.

This repo runs 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.
• list_property_annotations: Returns the annotations configured on a property.

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.
• run_conversions_report: Runs a Google Analytics conversions 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.

Write / configure a property (fork addition) ✍️

Not in the upstream read-only server. These make permanent changes and require the analytics.edit scope and an Editor / Administrator role on the target property.

• create_custom_dimension: Creates a custom dimension on a GA4 property — permanently registers an event/user/item parameter so it becomes reportable.
• create_key_event: Marks an event as a Key Event / conversion on a GA4 property.

Setup instructions 🔧

Setup involves the following steps:

1. Install a runner (uv recommended).
2. Get the fork (clone it).
3. Enable the Google Analytics APIs in your Google Cloud project.
4. Configure credentials for Google Analytics.
5. Configure your MCP client (Gemini, Claude Code, …).

Install a runner 🐍

Install uv (used to run the server from source). pipx also works if you prefer to run a branch straight from GitHub.

Get the fork ⬇️

git clone https://github.com/adtechnacity/ga-mcp.git

Note the absolute path to the clone — you'll reference it as PATH_TO_REPO below.

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 principal with access to your Google Analytics accounts or properties.

This fork requests two scopes — the read scope used by all read tools, and the edit scope required by the write tools:

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

If you only intend to use the read tools, the edit scope is harmless (it's still requested, but unused). To actually create custom dimensions / key events, the principal must also hold an Editor / Administrator role on the target GA4 property — the scope alone is not enough.

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. You'll need it for the next step.

Using a service account (e.g. for headless / CI use)? Set GOOGLE_APPLICATION_CREDENTIALS to the key file in your MCP client env (see below). Remember the service account still needs the Editor / Administrator property role for writes.

Configure Gemini

1. Install Gemini CLI or Gemini Code Assist.

2. Create or edit ~/.gemini/settings.json, adding the server to the mcpServers list. Replace PATH_TO_REPO with the path to your clone and YOUR_PROJECT_ID with your project ID. Set GOOGLE_APPLICATION_CREDENTIALS only if you're using a service-account key file rather than ADC.

   {
     "mcpServers": {
       "analytics-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "PATH_TO_REPO",
           "run",
           "python",
           "-m",
           "analytics_mcp.server"
         ],
         "env": {
           "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"
         }
       }
     }
   }
   

Configure Claude Code

Add the MCP server, running it from your clone with uv. Replace PATH_TO_REPO with the path to your clone and YOUR_PROJECT_ID with your project ID.

claude mcp add analytics-mcp \
  --scope user \
  -e "GOOGLE_PROJECT_ID=YOUR_PROJECT_ID" \
  -- uv --directory PATH_TO_REPO run python -m analytics_mcp.server

Add -e "GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIALS_JSON" if you're authenticating with a service-account key file instead of ADC.

Try it out 🥼

Launch your MCP client and list the available servers (e.g. /mcp in Gemini or Claude Code). You should see analytics-mcp with 11 tools.

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 property configuration:

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

• Use a write tool (needs the edit scope + an Editor role on the property):

  create an event-scoped custom dimension named "Respin Genre" for the
  parameter fs_respin_genre on property 123456789
  

Relationship to upstream 🔗

This fork tracks googleanalytics/google-analytics-mcp as upstream. The only additions are the two Admin-API write tools and the analytics.edit scope; the read tools are unchanged. Source-file copyright headers from upstream are retained (Apache-2.0). Generally-useful fixes are welcome here, but consider sending broadly-applicable changes upstream too — see CONTRIBUTING.md.

Contributing ✨

Contributions welcome! See the Contributing Guide.