Metadata-Version: 2.4
Name: analytics-mcp
Version: 1.0.0
Summary: MCP server for Google Analytics
Author-email: Josh Radcliff <jradcliff@users.noreply.github.com>, Matt Landers <matt-landers@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: homepage, https://github.com/googleanalytics/google-analytics-mcp
Project-URL: repository, https://github.com/googleanalytics/google-analytics-mcp.git
Project-URL: issues, https://github.com/googleanalytics/google-analytics-mcp/issues
Keywords: google analytics,analytics,mcp,ga4
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-analytics-data==0.23.3
Requires-Dist: google-analytics-admin==0.30.2
Requires-Dist: google-auth~=2.62
Requires-Dist: mcp<3,>=2.3.0
Requires-Dist: google-adk>=2.11.0
Requires-Dist: httpx>=0.28.1
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: nox<2027,>=2026.2.9; extra == "dev"
Dynamic: license-file

# Google Analytics MCP Server

[![PyPI version](https://img.shields.io/pypi/v/analytics-mcp.svg)](https://pypi.org/project/analytics-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![GitHub branch check runs](https://img.shields.io/github/check-runs/googleanalytics/google-analytics-mcp/main)](https://github.com/googleanalytics/google-analytics-mcp/actions?query=branch%3Amain++)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/analytics-mcp)](https://pypi.org/project/analytics-mcp/)
[![GitHub stars](https://img.shields.io/github/stars/googleanalytics/google-analytics-mcp?style=social)](https://github.com/googleanalytics/google-analytics-mcp/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/googleanalytics/google-analytics-mcp?style=social)](https://github.com/googleanalytics/google-analytics-mcp/network/members)
[![YouTube Video Views](https://img.shields.io/youtube/views/PT4wGPxWiRQ)](https://www.youtube.com/watch?v=PT4wGPxWiRQ)

This repo contains the source code for running a local
[MCP](https://modelcontextprotocol.io) server that interacts with APIs for
[Google Analytics](https://support.google.com/analytics).

Join the discussion and ask questions in the
[🤖-analytics-mcp channel](https://discord.com/channels/971845904002871346/1398002598665257060)
on Discord.

## 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 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](https://youtu.be/nS8HLdwmVlY) on YouTube for a step-by-step
walkthrough of these instructions.

[![Watch the video](https://img.youtube.com/vi/nS8HLdwmVlY/mqdefault.jpg)](https://www.youtube.com/watch?v=nS8HLdwmVlY)

Setup involves the following steps:

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

### Configure Python 🐍

[Install pipx](https://pipx.pypa.io/stable/#install-pipx).

### 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 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](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/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/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](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 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](https://support.google.com/googleapi/answer/7014113) of your
    Google Cloud project.

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

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

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

  ```shell
  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`](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](CONTRIBUTING.md).
