Skip to content

Light version: pages open quickly, without the 3D graphics. You are seeing the light version because the 3D graphics would be slow on this device. The content is the same.

Turn on 3D

Preparing the graphics. This can take a moment on the first visit.

Henry Lõiv

Web design & development

GuideArtificial Intelligence 13 min read

Google Analytics MCP: Claude and Codex setup on Mac and Windows

Connect GA4 to Claude or Codex on macOS and Windows with a free local MCP server. Read-only OAuth setup, useful prompts and fixes for common errors.

You can connect Google Analytics 4 to Claude Desktop, Claude Code or Codex without paying for a hosted MCP connector. Google's open-source Analytics MCP server runs on your computer and gives your assistant tools to retrieve your own GA4 reports. You can then ask about traffic, landing pages and recorded events without exporting a CSV for each question. Google's Analytics MCP guide

I set up both Analytics and Search Console MCPs locally on my Mac on 4 November 2026. This guide follows the Analytics connection, including the credential problem I encountered along the way.

The setup uses the Analytics read-only permission. Choose the instructions for your operating system, then configure the AI client you actually use. You do not need all three clients.

Checked on 4 November 2026: the original macOS connection used Python 3.13, analytics-mcp 0.7.0 and google-auth-oauthlib 1.5.0; account discovery and a live GA4 report succeeded. The Windows instructions were checked against the platform documentation, but have not been tested end to end on Windows. The commands retain the tested package versions. Analytics MCP 1.0.0 was released on 3 November; it needs a fresh integration test before replacing that pin in this guide.

What you get, and what is free

MCP stands for Model Context Protocol. In this setup, it lets an assistant call tools that read Analytics accounts, properties and reports. A useful first request is:

Show sessions by landing page for the last seven complete days. Include the property ID, property timezone and exact date range. Flag any recent data that may still change.

The local server has no subscription fee, and standard Google Analytics does not require an Analytics 360 subscription. Your assistant's plan or API usage still costs whatever it normally costs, and Google API quotas still apply. This setup does not require a paid MCP gateway, a cloud server or BigQuery. Google Analytics · Server licence · Data API quotas

The server runs locally, but the report results you request are passed to the assistant. This is not an offline AI workflow.

Before you start

You need:

  • A Google account with at least Viewer access to the GA4 property you want to analyse.
  • A Google Cloud project where you can enable APIs and create an OAuth client. The Cloud project and the GA4 property are separate resources.
  • One installed client: Claude Desktop, Claude Code or a local Codex client. The CLI configuration commands below require the relevant CLI to be installed.
  • macOS: Homebrew and Terminal. Windows: native PowerShell and Python 3.13; WinGet is used below to install Python.

The Windows steps target native Windows clients. A server installed inside WSL is a separate environment; its Linux paths will not work in the native Claude Desktop configuration.

1. Install Python, pipx and the Analytics MCP server

pipx keeps the server's dependencies in their own Python environment. Follow only your platform's subsection. If pipx reports that Analytics MCP is already installed, inspect pipx list before replacing a working installation.

macOS

Install Python 3.13 and pipx:

brew install python@3.13 pipx
pipx ensurepath

Open a new Terminal window, then install the versions used for this guide:

pipx install --python "$(brew --prefix python@3.13)/bin/python3.13" analytics-mcp==0.7.0
pipx inject analytics-mcp google-auth-oauthlib==1.5.0
command -v analytics-mcp

Windows PowerShell

If Python 3.13 is not installed, run:

winget install --id Python.Python.3.13 --exact --source winget

Reopen PowerShell after installation. Then install pipx and add its commands to your user PATH:

py -3.13 --version
py -3.13 -m pip install --user pipx
py -3.13 -m pipx ensurepath

Close and reopen your terminal application again. Install the MCP server using the actual Python 3.13 executable:

$GaBasePython = (py -3.13 -c "import sys; print(sys.executable)").Trim()
pipx install --python "$GaBasePython" "analytics-mcp==0.7.0"
pipx inject analytics-mcp "google-auth-oauthlib==1.5.0"
(Get-Command analytics-mcp -CommandType Application).Source

Keep the executable path printed by the last command on either platform. Desktop apps may not inherit your terminal's PATH, so their configuration will use the full path. No virtual-environment activation is needed. pipx installation · PyPA Windows instructions · Python on Windows

2. Enable the Google APIs and create a Desktop OAuth client

In Google Cloud Console, use the same project throughout these steps:

  1. Create or select your project. Record its project ID, which is different from its display name and numeric project number.
  2. Open APIs & Services → Library and enable Google Analytics Admin API and Google Analytics Data API.
  3. Open Google Auth Platform. If the app has not been configured, select Get started and complete its name, support email and contact information.
  4. Choose the appropriate audience. For a personal Google account, use External. If the app remains in Testing, add the Google account you will sign in with under Audience → Test users.
  5. Under Data Access, add the scope https://www.googleapis.com/auth/analytics.readonly using Add or remove scopes.
  6. Open Clients → Create client, select Desktop app, and create the client. Download its JSON when offered.

The Google account you authorise must also have access to your GA4 property. Enabling an API does not grant that access. Google's Auth Platform introduction, OAuth client guide and scope configuration guide explain these settings.

For an External app in Testing, authorisations using the Analytics scope expire after seven days, including offline refresh tokens. You can reauthorise during testing. For longer-term use, review Google's publishing and verification requirements; changing the publishing status does not make tokens permanent. Google's audience and Testing rules

Save the downloaded client JSON

Create a folder outside your repositories.

macOS:

mkdir -p "$HOME/.config/google-analytics-mcp"
chmod 700 "$HOME/.config/google-analytics-mcp"

Windows PowerShell:

$GaRoot = Join-Path $HOME ".config\google-analytics-mcp"
New-Item -ItemType Directory -Force -Path $GaRoot | Out-Null
$GaRoot

Save the downloaded file inside that folder as oauth_client.json. On Windows, check that the filename has not become oauth_client.json.txt.

On macOS, also restrict that file's permissions:

chmod 600 "$HOME/.config/google-analytics-mcp/oauth_client.json"

oauth_client.json identifies your OAuth app. The next step creates a separate credentials.json containing the authorisation for your Google account. Do not interchange the two files or commit them to Git. On Windows, keep this folder in your own user profile; Unix permission commands are not Windows access controls.

3. Authorise read-⁠only access

This small helper uses Google's OAuth library to create a dedicated ADC-style credential file. It avoids replacing another application's default Google login. It is a helper for this guide; Google's upstream instructions also document a gcloud authentication route.

Save the following as authorize.py in the same folder as oauth_client.json. Use a plain-text editor such as VS Code; on Windows, save it as authorize.py, not authorize.py.txt.

You can also download the same OAuth helper, rename it to authorize.py, and save it in that folder.

import json
import os
from pathlib import Path

from google_auth_oauthlib.flow import InstalledAppFlow

if os.name != "nt":
    os.umask(0o077)

root = Path.home() / ".config" / "google-analytics-mcp"
root.mkdir(parents=True, exist_ok=True)
if os.name != "nt":
    root.chmod(0o700)

client = json.loads(
    (root / "oauth_client.json").read_text(encoding="utf-8-sig")
)
if "installed" not in client:
    raise SystemExit("Use an OAuth client JSON created for a Desktop app.")
project = client["installed"].get("project_id")
if not project:
    raise SystemExit("The OAuth client JSON is missing project_id.")

flow = InstalledAppFlow.from_client_config(
    client,
    scopes=["https://www.googleapis.com/auth/analytics.readonly"],
)
credentials = flow.run_local_server(
    port=0, prompt="consent", access_type="offline"
)
if not credentials.refresh_token:
    raise SystemExit("Google did not return a refresh token. Authorise again.")

data = json.loads(credentials.to_json())
data.update(type="authorized_user", quota_project_id=project)
path = root / "credentials.json"
path.write_text(json.dumps(data, indent=2), encoding="utf-8")
if os.name != "nt":
    path.chmod(0o600)

print("Credentials:", path)
print("Project:", project)

Run it with the Python interpreter from this package's pipx environment. Discovering PIPX_HOME avoids assuming where pipx stores its files on your machine. pipx path configuration

macOS:

GA_PYTHON="$(pipx environment --value PIPX_HOME)/venvs/analytics-mcp/bin/python"
"$GA_PYTHON" "$HOME/.config/google-analytics-mcp/authorize.py"

Windows PowerShell:

$GaPipxHome = (pipx environment --value PIPX_HOME).Trim()
$GaPython = Join-Path $GaPipxHome "venvs\analytics-mcp\Scripts\python.exe"
& $GaPython (Join-Path $HOME ".config\google-analytics-mcp\authorize.py")

Complete the browser sign-in with the account that can access your GA4 property. Review and approve the Analytics read permission. Keep the printed credential path and project ID for the next step. The helper prints no access or refresh tokens. Google's installed-app OAuth flow

4. Connect Claude Desktop, Claude Code or Codex

Choose one client subsection. If you use several clients, configure each separately; they can all read the same credential file.

For the Codex and Claude Code CLI commands, first set these variables in the terminal where you will run the command. Replace YOUR_PROJECT_ID with the project ID printed by the helper.

macOS:

GA_COMMAND="$(command -v analytics-mcp)"
GA_CREDENTIALS="$HOME/.config/google-analytics-mcp/credentials.json"
GA_PROJECT="YOUR_PROJECT_ID"

Windows PowerShell:

$GaCommand = (Get-Command analytics-mcp -CommandType Application).Source
$GaCredentials = Join-Path $HOME ".config\google-analytics-mcp\credentials.json"
$GaProject = "YOUR_PROJECT_ID"

Codex

macOS:

codex mcp add google-analytics \
  --env "GOOGLE_APPLICATION_CREDENTIALS=$GA_CREDENTIALS" \
  --env "GOOGLE_CLOUD_PROJECT=$GA_PROJECT" \
  -- "$GA_COMMAND"

Windows PowerShell:

codex mcp add google-analytics --env "GOOGLE_APPLICATION_CREDENTIALS=$GaCredentials" --env "GOOGLE_CLOUD_PROJECT=$GaProject" -- "$GaCommand"

This uses the user-level Codex configuration, shared by local Codex clients. A repository's .codex/config.toml has project scope. Inspect codex mcp list to confirm the entry exists, then open a new session. Codex MCP configuration

Claude Code

macOS:

claude mcp add \
  --env "GOOGLE_APPLICATION_CREDENTIALS=$GA_CREDENTIALS" \
  --env "GOOGLE_CLOUD_PROJECT=$GA_PROJECT" \
  --scope user --transport stdio \
  google-analytics -- "$GA_COMMAND"

Windows PowerShell:

claude mcp add --env "GOOGLE_APPLICATION_CREDENTIALS=$GaCredentials" --env "GOOGLE_CLOUD_PROJECT=$GaProject" --scope user --transport stdio google-analytics -- "$GaCommand"

--scope user makes the server available across your projects on that computer. Start a new Claude Code session and check /mcp. Claude Code MCP scopes

Claude Desktop

Open Claude Desktop's developer configuration and merge the server entry below into the existing mcpServers object. Preserve the other servers and settings. Do not create two top-level mcpServers keys.

PlatformConfiguration file
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json

On Windows, %APPDATA% is a File Explorer address; PowerShell exposes the same location as $env:APPDATA. If needed, use Claude Desktop's developer settings to open or create the configuration file.

macOS example:

{
  "mcpServers": {
    "google-analytics": {
      "command": "/ABSOLUTE/PATH/analytics-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOUR_NAME/.config/google-analytics-mcp/credentials.json",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Windows example:

{
  "mcpServers": {
    "google-analytics": {
      "command": "C:/Users/YOUR_NAME/.local/bin/analytics-mcp.exe",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:/Users/YOUR_NAME/.config/google-analytics-mcp/credentials.json",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Replace the command with the actual executable path from step 1, and replace the username and project ID. Use full paths: $HOME, %APPDATA% and ~ are not expanded inside these JSON examples. Forward slashes in Windows JSON avoid backslash escaping errors. Save as UTF-8, then fully quit and reopen Claude Desktop. Google's Claude client examples

5. Verify a real GA4 report

First ask:

Use the Google Analytics MCP tools to list the accounts and properties I can access. Show each property's name and numeric property ID. Wait for me to choose one.

After choosing a property, ask:

For that property, retrieve sessions for the last seven complete days using its reporting timezone. Show the exact dates and daily values. Explain whether the most recent data may still be incomplete.

A successful report request returns a table for the selected property. If it fails, inspect the actual API error. A green MCP connection indicator alone is not enough: starting the process, authenticating and reading a property are separate checks. Compare a small report with GA4 using the same property, dates, filters and metric definitions. This short answer explains why Search Console clicks and GA4 sessions differ.

A useful first analysis: which visits lead to meaningful activity?

Once the connection works, try this sequence:

  1. Compare traffic: “Compare 28 complete days ending three days ago with the preceding 28 days. Use the property's timezone and show both exact date ranges. Break down sessions, engaged sessions and engagement rate by channel. Separate measured changes from possible explanations.”
  2. Inspect landing pages: “For those periods, show the ten landing pages with the most sessions. Include session counts and engagement rate. Flag small samples before recommending changes.”
  3. Check your events: “List the event names recorded in this period. If a form submission or lead event exists, let me choose the correct event before comparing it by landing page. If it is not recorded, explain what is missing.”

The connection cannot reconstruct events your site never tracked. It also does not make an assistant's interpretation automatically correct. Ask it to show the report behind each conclusion.

Recent GA4 data can change during processing; Google notes that processing can take 24–48 hours. Exact dates and a suitable reporting delay make comparisons easier to check. GA4 data freshness

For search queries, Google impressions and click-through rates, add the Google Search Console MCP connection. GA4 and Search Console answer different parts of the question, and their sessions and clicks should not be treated as interchangeable counts.

Google Analytics MCP troubleshooting

invalid_grant or authorisation stopped working

Run authorize.py again, then restart the MCP clients so they load the new credentials. Check whether the OAuth app is still in Testing, whether access was revoked, or whether account policies require another sign-in. The original macOS setup returned invalid_grant while using older authorisation; restarting mattered after the credential file was replaced. Google's refresh-token rules. See why a Google OAuth connection can stop working after seven days.

403, API not enabled or no accessible properties

Confirm that both Analytics APIs are enabled in the project used for this OAuth client and GOOGLE_CLOUD_PROJECT. Check the account used during sign-in and its GA4 property access. If you see an insufficient-scope error, reauthorise with the helper rather than substituting a different Google credential file.

pipx, py or the executable is not found on Windows

If py -3.13 is unavailable, check the Python installation and launcher, then reopen the terminal. If pipx is unavailable, run py -3.13 -m pipx ensurepath and fully reopen the terminal application. For desktop launch errors, use the complete path returned by Get-Command analytics-mcp; for macOS, use command -v analytics-mcp.

The server works only in one repository

Check that Claude Code has a user-scoped entry. For Codex, inspect the user configuration as well as any repository configuration. A project entry with the same server name may change which settings take effect. After changing configuration, start a new client session.

The JSON file cannot be read

Use the downloaded Desktop app client JSON as oauth_client.json, and the helper's output as credentials.json. Confirm the actual file extensions and full paths. In Claude Desktop's JSON, use forward slashes on Windows or escape each backslash as \\; do not add shell variables or comments.

Can this change Analytics settings or work in every web chat?

This setup requests analytics.readonly and does not enable write tools. Keep that distinction when upgrading: newer server versions may offer optional write features.

These instructions configure local MCP clients. Adding a server to a local configuration does not automatically create a connector in the Claude website or every ChatGPT conversation. Verify the integration in the app or CLI you configured.

Official references

Putting AI to work on your website?

Choosing a model is one part of a working feature. If your business needs a support assistant, content workflow or connection to an existing system, I can help define and build the interface, integrations and checks it needs.

Explore AI integrations for websites and applications⁠

Written by Henry Lõiv

Related guides

  1. How to use Search Console and GA4 with AI to choose website improvements Use Search Console and GA4 through MCP to choose website improvements. A worked fictional example, priority worksheet and prompts for checking the results. GuideSEO & AI Search 4 min read

Keep reading

All articles⁠
  1. AI Agent, Chatbot or Automation: What Does Your Business Need? A chatbot is an interface; an agent is one way to handle the work behind it. Follow a fictional customer enquiry to choose a practical system for your business. Artificial Intelligence 8 min read
  2. Claude Code vs Codex for Frontend Development: A Practical Comparison A documentation-based comparison with a runnable frontend exercise and a blank scorecard. No measured winner is claimed. Artificial Intelligence 9 min read
  3. Is Your AI-Built Website Ready for Real Customers? A practical website review using a clearly fictional example, with a downloadable launch checklist. Artificial Intelligence 9 min read

Hi!

I really love the sea, yachts, sunsets and starry skies.

Through this little 3D world, I can share a small part of myself with you.

Thank you for opening this bottle and reading my letter.

Henry

Let’s talk about your project

Tell me about your project

Tell me what you’d like to build or improve. You don’t need a finished brief — we’ll work out the scope and next steps together.

01 How can I help?
02 How many pages do you need?
03 Which extras do you need? Choose all that apply
04 When does it need to be ready?
05 Project details
06 Your contact details

Enquiry received

Thank you!

Your enquiry has been received. I usually reply by email within 2 working days.