GA4 Export

ga4-export is a Node.js CLI and stdio MCP server for exporting Google Analytics 4 and Google Search Console data into local files that LLM agents can read.

It is designed for Claude Code, Cursor, Codex, local LLM agents, and any tool that can either run a command or connect to a stdio MCP server.

What It Does

• Sync all GA4 accounts and properties visible to a service account.
• Export aggregated GA4 Data API reports to CSV or JSONL.
• Export Google Search Console query rows and low-CTR keyword opportunities.
• Write CONTEXT.md, per-export README.md, and manifest.json files for model analysis.
• Expose the same workflows through a stdio MCP server.

It does not export raw GA4 event-level data. Use GA4 BigQuery Export if you need raw events.

Install

From a published package:

npm install -g ga4-export

From a local checkout:

git clone <your-repo-url> ga4-export
cd ga4-export
npm install
npm link

Verify:

ga4-export --help
ga4-export-mcp --help

ga4-export-mcp is a stdio server, so it does not print a normal help screen. Use the MCP smoke test below.

Architecture

bin/
├─ ga4-export.js       # CLI entrypoint
└─ ga4-export-mcp.js   # stdio MCP entrypoint

src/
├─ cli.js              # command parsing and terminal output
├─ mcp-server.js       # JSON-RPC / MCP protocol surface
├─ service.js          # shared orchestration used by CLI and MCP
├─ auth.js             # Google credential loading
├─ client.js           # GA4 REST client
├─ exporter.js         # GA4 report file writer
├─ search-console.js   # Search Console query export
├─ properties.js       # property discovery and alias resolution
├─ reports.js          # built-in GA4 report definitions
└─ context.js          # model-facing context writer

The stable internal boundary is src/service.js. CLI, MCP, and future integrations should call this layer instead of duplicating export flow.

Environment

Copy the template and fill in your local values:

cp examples/env.example .env

Typical shell setup:

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.secrets/ga4-reader.json"
export GA4_EXPORT_DIR="$HOME/ga4-data"
export GSC_AUTH_MODE=user_adc
export GSC_QUOTA_PROJECT="<your-google-cloud-project-id>"

Supported variables:

| Variable | Purpose | | --- | --- | | GOOGLE_APPLICATION_CREDENTIALS | Path to a GA4 service account JSON key. | | GA4_SERVICE_ACCOUNT_JSON | Service account JSON content or base64 JSON. Overrides file ADC when set. | | GA4_EXPORT_DIR | Local export directory. Defaults to ~/ga4-data. | | GA4_CONFIG | Optional JSON config path. Defaults to ~/.config/ga4-export/config.json. | | GA4_DEFAULT_DAYS | Default relative export window. Defaults to 30. | | GA4_QUOTA_PROJECT | Optional quota project for GA4 Google credentials. | | GSC_AUTH_MODE | service_account or user_adc. Defaults to service-account style credentials. | | GSC_GOOGLE_APPLICATION_CREDENTIALS | Optional separate credential file for Search Console. | | GSC_QUOTA_PROJECT | Quota project used for Search Console requests. |

Do not commit .env or service account JSON files.

GA4 Setup

1. Create a Google Cloud project or reuse an existing one.
2. Enable the GA4 APIs:

gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com \
  --project <your-google-cloud-project-id>

3. Create a service account key and save it outside the repo, for example:

$HOME/.secrets/ga4-reader.json

4. Find the service account email:

jq -r .client_email "$GOOGLE_APPLICATION_CREDENTIALS"

5. Add that email to GA4:

GA4 -> Admin -> Account access management -> Add user
Role: Viewer or Analyst

Prefer account-level access over property-level access when you manage many properties.

Validate:

ga4-export auth doctor
ga4-export properties sync
ga4-export properties list

Optional: Bulk Grant GA4 Access

If your human Google user already has GA4 user-management permission, you can grant one service account access across visible GA4 accounts:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/analytics.manage.users,openid,https://www.googleapis.com/auth/userinfo.email

ga4-export access grant-service-account \
  --service-account-email "$(jq -r .client_email "$GOOGLE_APPLICATION_CREDENTIALS")" \
  --role viewer \
  --dry-run

Remove --dry-run only after checking the account list.

GA4 Export Commands

Export all visible properties for the last 30 days:

ga4-export pull --property all --last 30d
ga4-export context --property all

Export one property by alias, property ID, resource name, or property name:

ga4-export pull --property <property-alias> --last 30d

Export a fixed date range:

ga4-export pull --property all --from 2026-03-01 --to 2026-03-31

Export selected built-in reports:

ga4-export pull --property all --last 30d --reports acquisition,landing_pages,events

Export a custom GA4 Data API report:

ga4-export pull \
  --property all \
  --last 30d \
  --dimensions hostName \
  --metrics sessions,totalUsers \
  --report-name hostnames

List built-in reports:

ga4-export reports list

Search Console Setup

Search Console is used for query-level SEO data:

query, clicks, impressions, ctr, average position

For many teams, the simplest setup is user ADC:

gcloud services enable searchconsole.googleapis.com \
  --project <your-google-cloud-project-id>

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/webmasters.readonly,openid,https://www.googleapis.com/auth/userinfo.email

gcloud auth application-default set-quota-project <your-google-cloud-project-id>

export GSC_AUTH_MODE=user_adc
export GSC_QUOTA_PROJECT=<your-google-cloud-project-id>

The authenticated user must be a verified owner or full user for the Search Console property.

Validate:

ga4-export search-console sites

Export query opportunities:

ga4-export search-console pull \
  --site all \
  --last 30d \
  --min-impressions 50 \
  --low-ctr 0.02

Output Layout

$GA4_EXPORT_DIR/
├─ properties.json
├─ CONTEXT.md
├─ <property-alias>/
│  ├─ metadata.json
│  └─ <start>_<end>/
│     ├─ acquisition.csv
│     ├─ landing_pages.csv
│     ├─ pages.csv
│     ├─ events.csv
│     ├─ key_events.csv
│     ├─ geo.csv
│     ├─ devices.csv
│     ├─ manifest.json
│     └─ README.md
└─ search-console/
   └─ <site>/
      └─ <start>_<end>/
         ├─ queries.csv
         ├─ opportunities.csv
         ├─ manifest.json
         └─ README.md

For model analysis, start with:

$GA4_EXPORT_DIR/CONTEXT.md

Then inspect the relevant manifest.json, CSV, and opportunities.csv files.

MCP Usage

If ga4-export-mcp is available on PATH, project-level MCP config can be minimal:

{
  "mcpServers": {
    "ga4-export": {
      "type": "stdio",
      "command": "ga4-export-mcp",
      "args": []
    }
  }
}

If your MCP client does not inherit shell environment variables, copy examples/mcp.json and fill in absolute local paths.

Smoke test:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | ga4-export-mcp

See docs/MCP.md for Claude Code, Cursor, and generic stdio MCP examples.

Agent Skill

The repo includes a reusable analysis skill at:

.agents/skills/ga4-data-analysis/SKILL.md

Install it into Codex-style skill directories:

mkdir -p "$HOME/.codex/skills"
cp -R .agents/skills/ga4-data-analysis "$HOME/.codex/skills/"

Example prompt:

Use ga4-data-analysis to inspect my latest GA4 and Search Console exports.
Find high-impression low-CTR keyword opportunities and give project-specific next actions.

Security

• Keep service account JSON files outside the repository.
• Use chmod 600 for local JSON key files.
• Grant the service account the minimum GA4 role needed, usually Viewer or Analyst.
• Use user ADC for Search Console when a personal verified owner is required.
• Do not put raw private keys, refresh tokens, or personal emails into committed MCP configs.

Development

npm install
npm test
npm run smoke:mcp

Open-source checklist:

• README.md and docs/ contain placeholders, not personal paths.
• .mcp.json and .cursor/mcp.json are portable examples.
• examples/env.example is safe to commit.
• Service account keys, .env, node_modules, and local export data are ignored.