# Google Analytics MCP Server — adtechnacity fork (Experimental)

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

> **This is a fork.** It is based on
> [`googleanalytics/google-analytics-mcp`](https://github.com/googleanalytics/google-analytics-mcp)
> (Apache-2.0) and maintained at
> [`adtechnacity/ga-mcp`](https://github.com/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](#setup-instructions-)).
>
> ⚠️ 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](https://modelcontextprotocol.io) server that
interacts with APIs for
[Google Analytics](https://support.google.com/analytics).

## Tools 🛠️

The server uses the
[Google Analytics Admin API](https://developers.google.com/analytics/devguides/config/admin/v1)
and
[Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)
to provide several
[Tools](https://modelcontextprotocol.io/docs/concepts/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`](https://docs.astral.sh/uv/) recommended).
1.  Get the fork (clone it).
1.  Enable the Google Analytics APIs in your Google Cloud project.
1.  Configure credentials for Google Analytics.
1.  Configure your MCP client (Gemini, Claude Code, …).

### Install a runner 🐍

Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (used to
run the server from source). [`pipx`](https://pipx.pypa.io/stable/#install-pipx)
also works if you prefer to run a branch straight from GitHub.

### Get the fork ⬇️

```shell
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](https://support.google.com/googleapi/answer/6158841)
to enable the following APIs in your Google Cloud project:

- [Google Analytics Admin API](https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com)
- [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com)

### Configure credentials 🔑

Configure your [Application Default Credentials
(ADC)](https://cloud.google.com/docs/authentication/provide-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](https://support.google.com/cloud/answer/15549257)
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`.

  ```shell
  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.

  ```shell
  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](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.md)
    or [Gemini Code
    Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist).

1.  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](https://support.google.com/googleapi/answer/7014113). Set
    `GOOGLE_APPLICATION_CREDENTIALS` only if you're using a service-account key
    file rather than ADC.

    ```json
    {
      "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](https://support.google.com/googleapi/answer/7014113).

```shell
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`](https://github.com/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.md).

## Contributing ✨

Contributions welcome! See the [Contributing Guide](CONTRIBUTING.md).