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:
- Create or select your project. Record its project ID, which is different from its display name and numeric project number.
- Open APIs & Services → Library and enable Google Analytics Admin API and Google Analytics Data API.
- Open Google Auth Platform. If the app has not been configured, select Get started and complete its name, support email and contact information.
- 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.
- Under Data Access, add the scope
https://www.googleapis.com/auth/analytics.readonlyusing Add or remove scopes. - 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.
| Platform | Configuration 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:
- 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.”
- 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.”
- 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
- Google Analytics MCP setup and tools
- Analytics MCP source and releases
- Analytics MCP on PyPI
- Google Auth Platform
- Google OAuth refresh-token rules
- pipx installation
- Microsoft WinGet installation command
- Codex MCP configuration
- Claude Code MCP configuration
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.