Skip to main content
Glama
google-measurement-mcp

google-measurement-mcp

Google Measurement MCP

Investigate traffic and tracking across Google Analytics 4, Search Console, and Google Tag Manager from your AI assistant.

One local MCP server, installed through npm. Start with 20 read tools. Enable 8 editing and staging tools explicitly. Live publishing stays in Google Tag Manager.

0.2.0 is in development. The published npm release is currently 0.1.0. The behavior described here applies to this checkout; use the source setup below until 0.2.0 is released. Migration notes

Try the demonstration — no Google account needed

Fictional demonstration of Search Console comparison and pagination

git clone https://github.com/jabeer4148-ops/google-measurement-mcp.git
cd google-measurement-mcp
npm ci
npm run demo

Open docs/demo/index.html in a browser. It uses fictional data passed through the real tool handlers: compare search periods, recover paginated results, and detect a changed GTM tag whose name stayed the same. No credentials or Google API calls are involved. Demo guide

Related MCP server: Antigravity Google Workspace MCP Server

Start with a useful question

  • “Compare Search Console clicks and impressions between these two completed weeks.”

  • “Show my top organic landing pages in GA4, ordered by sessions.”

  • “What changed inside this GTM version, including tags with unchanged names?”

The tools return data for your assistant to interpret. A configuration review does not prove that a tag fired on a live website. Query limits and data-quality indicators matter.

Connect your Google account

Requires Node.js 22+, a local MCP client, and a Google account with access to the properties you want to inspect. This is a local stdio server; remote web connectors are not supported.

1. Set up a Google Cloud desktop OAuth client

In your Google Cloud project, enable Analytics Data API, Analytics Admin API, Search Console API, and Tag Manager API. Configure Google Auth Platform and create an OAuth client of type Desktop app. Download its JSON and keep it outside this repository. Use a neutral consent-screen name such as Measurement MCP.

If your OAuth app is External and in Testing, add your account as a test user. Refresh tokens for these scopes normally expire after seven days in Testing. Review Google's publishing/verification requirements for your particular app before changing its publishing status; production status and verification are different concepts. Google OAuth documentation

2. Sign in explicitly

For the unreleased source checkout:

npm ci
npm run build
export GMCP_OAUTH_CLIENT_JSON=/absolute/path/to/desktop-client.json
node dist/index.js --auth

Windows PowerShell:

npm ci
npm run build
$env:GMCP_OAUTH_CLIENT_JSON = 'C:\path\outside-repo\desktop-client.json'
node dist/index.js --auth

Open the printed URL and complete sign-in. The refresh token is cached under ~/.config/google-measurement-mcp/ (or XDG_CONFIG_HOME). The OAuth flow validates state and uses S256 PKCE. Normal server startup never opens a login flow.

3. Configure your MCP client

Claude Desktop / Cursor-style configuration for this checkout:

{
  "mcpServers": {
    "google-measurement": {
      "command": "node",
      "args": ["/absolute/path/to/google-measurement-mcp/dist/index.js"],
      "env": {
        "GMCP_OAUTH_CLIENT_JSON": "/absolute/path/to/desktop-client.json"
      }
    }
  }
}

Use escaped Windows paths in JSON, such as C:\\path\\desktop-client.json. Restart the MCP client, then ask it to call gmcp_diagnostics, followed by gsc_list_sites or ga4_list_account_summaries. Success means the intended property is visible, not just that the process starts.

After 0.2.0 is published, the package command will be npx -y google-measurement-mcp@0.2.0. Do not substitute the currently published 0.1.0 and expect the new tools or protections.

Service accounts and ADC

For headless use, set GOOGLE_APPLICATION_CREDENTIALS to a service-account key outside the repo, and grant that identity appropriate product-level access. Use read/view permissions for read-only work; additional editor permissions are needed for staging. No publish permission is required by this server.

Existing Application Default Credentials are the fallback. The resolution order is configured service-account credentials, configured user OAuth, then ADC. A browser's Google login is independent of the API identity. Call product discovery tools to confirm access before testing a specific resource.

Editing and review

Add --enable-write to the server arguments, or set GMCP_ENABLE_WRITE=1. Run --auth --enable-write to grant the required editing scopes if your cached login only has read scopes.

  • Write tools are absent in the default mode.

  • GTM tag/trigger edits are staged in a workspace. Updates preserve fetched fields and use fingerprints to reject concurrent changes.

  • gtm_create_version creates a reviewable version; check its result and newWorkspacePath before further work.

  • gtm_preview_version compares the candidate with the live version, including modified fields. It is available in read-only mode.

  • There is no gtm_publish_version tool and no requested publish scope. Review and publish manually in Google Tag Manager. v0.1's caller-supplied confirmation flag did not establish independent human approval.

  • No dedicated delete/archive tools are exposed. Editing existing configuration still has consequences, and other people can publish staged changes from GTM.

For gtm_update_tag, omitted fields are preserved. parameter merges by key; parameter: [] explicitly clears parameters. Empty trigger arrays deliberately clear trigger bindings. Review before making these changes.

Credentials are stored locally. Tool results go to your selected AI client/provider; local execution is not a promise that all analytics data stays on your machine.

Tools

Read — available by default (20)

Tool

Purpose

gmcp_diagnostics

Check auth and mode without exposing secrets

ga4_get_metadata

Discover valid dimensions and metrics

ga4_list_account_summaries

Discover accounts and property IDs

ga4_run_report

Reports with filters, sorting, quality metadata and row caps

ga4_run_realtime_report

Recent activity using GA4's realtime schema

ga4_list_custom_dimensions

Custom dimension definitions

ga4_list_key_events

Key-event definitions

gsc_list_sites

Discover exact property strings

gsc_search_analytics_query

Search performance, filters and offset pagination

gsc_compare_periods

Compare two equal-length completed periods

gsc_list_sitemaps

Submitted sitemap status

gsc_inspect_url

Index status for a specific URL

gtm_list_accounts

GTM account discovery

gtm_list_containers

Container discovery

gtm_list_workspaces

Workspace discovery

gtm_list_tags

Workspace tags and trigger bindings

gtm_list_triggers

Workspace trigger definitions

gtm_list_variables

User-defined workspace variables

gtm_get_live_version

Full published configuration; potentially large

gtm_preview_version

Candidate-versus-live configuration review

Editing/staging — requires opt-in (8)

ga4_create_custom_dimension, ga4_create_key_event, ga4_update_key_event, gsc_submit_sitemap, gtm_create_tag, gtm_update_tag, gtm_create_trigger, gtm_create_version.

Custom dimensions affect configuration and require care. Archiving can free quota but cannot be undone, and this server does not expose archival. Google's explanation

Configuration

Variable

Purpose

GMCP_OAUTH_CLIENT_JSON

Path to desktop OAuth client JSON

GMCP_OAUTH_CLIENT_ID, GMCP_OAUTH_CLIENT_SECRET

Alternative to the JSON file

GOOGLE_APPLICATION_CREDENTIALS

Service-account credential file

GMCP_ENABLE_WRITE

Enable editing/staging; unset by default

GMCP_DEFAULT_ROW_LIMIT

Default list/report cap; 25 by default

GMCP_TOKEN_PROFILE

Separate saved identity; letters, digits, _ and - only

GMCP_SMOKE is only for opt-in test runs, not normal operation.

Query correctness and limits

GA4 IDs are numeric property IDs, not G-... measurement IDs. Search Console property strings must match access exactly. GA4 accepts relative dates; Search Console requires real YYYY-MM-DD dates.

GA4/GTM listings return nextPageToken when more rows remain. Pass it unchanged with the same resource and limit. If a clipped upstream page changes, restart the listing rather than assuming a consistent inventory.

Search Console uses startRow / nextStartRow and caps requests at 25,000 rows. At the boundary, hasMore: "possible" signals that another request may be needed. Google returns top rows and does not guarantee the complete underlying search dataset. Query-level totals can differ from property totals. Compare equal-length periods and avoid interpreting clicks as GA4 sessions.

Alternatives

For GA4-only reporting and funnels, consider Google's official Analytics MCP. For dedicated SEO workflows see mcp-gsc; for dedicated GTM management see Stape's server.

Choose this project when a local Node/npm workflow across the three measurement products fits your work. It is an independent community project, not an official Google product.

Development and feedback

npm run typecheck
npm test
npm run test:safety
npm run test:protocol
npm run demo
npm run verify:package

Tests use fictional API responses; OAuth tests use a local loopback listener. No Google credentials are needed. Live checks are explicitly opt-in: testing guide.

If the project helps you complete a real task, consider starring it. Setup feedback and reproducible issues help improve it: contribution guide. Current work and migration notes are in CHANGELOG.md.

Apache-2.0 licensed.

Available Tools

20 tools
ga4_get_metadataDiscover GA4 dimensions and metricsA
Read-onlyIdempotent

Discover valid GA4 field names, descriptions and custom definitions for a property before reporting. Does not guarantee every combination is compatible.

Inputs: propertyId (required), limit.

ga4_list_account_summariesList GA4 accounts and propertiesA
Read-onlyIdempotent

Lists every Google Analytics account the authenticated user can see, with the properties under each. Use this FIRST to discover the numeric propertyId that other GA4 tools require. Returns account name, display name, and for each property its ID and display name. Read-only.

Inputs: limit, pageToken.

ga4_list_custom_dimensionsList GA4 custom dimensionsA
Read-onlyIdempotent

Lists custom dimensions configured on a GA4 property, with parameter name, display name, and scope (EVENT/USER/ITEM). Useful for discovering which custom dimensions exist before referencing them in ga4_run_report. Read-only.

Inputs: propertyId (required), limit, pageToken.

ga4_list_key_eventsList GA4 key eventsA
Read-onlyIdempotent

Lists key events (formerly 'conversions') on a GA4 property, with counting method and whether each is deletable. Read-only.

Inputs: propertyId (required), limit, pageToken.

ga4_run_realtime_reportRun a GA4 realtime reportA
Read-onlyIdempotent

Returns activity from roughly the last 30 minutes. Requires the NUMERIC GA4 propertyId (call ga4_list_account_summaries to find it). IMPORTANT: the realtime schema is a SUBSET of the standard reporting schema — 'date', 'sessionSource' and most session-scoped fields are unavailable and will error. Common realtime dimensions: country, city, deviceCategory, unifiedScreenName, eventName. Common realtime metrics: activeUsers, screenPageViews, eventCount. For anything older than 30 minutes use ga4_run_report instead. Read-only.

Inputs: metrics (required), propertyId (required), limit, dimensions.

ga4_run_reportRun a GA4 reportA
Read-onlyIdempotent

Runs a Google Analytics 4 report and returns rows as flat objects. Requires the NUMERIC GA4 propertyId (e.g. 123456789), not the G-XXXXXXX measurement ID. If the user does not know it, it appears in any GA4 URL as the digits after 'p' (analytics.google.com/analytics/web/#/ap/...), or under GA4 Admin -> Property details -> PROPERTY ID. Returns at most 25 rows unless limit is raised; prefer narrowing the date range or dimensions over raising it. Read-only.

Inputs: endDate (required), metrics (required), startDate (required), propertyId (required), +7 more.

gmcp_diagnosticsCheck connection and operating modeA
Read-onlyIdempotent

Check credential availability and read/write mode without exposing tokens or client secrets. Does not guarantee access to any particular property. Never starts browser sign-in.

Inputs: no named parameters.

gsc_compare_periodsCompare Search Console performance between periodsA
Read-onlyIdempotent

Compare web-search totals for two equal-length, non-overlapping date ranges using final data. Returns click/impression changes and CTR percentage-point change; zero baselines yield null percentage change. Uses two read requests.

Inputs: endDate (required), siteUrl (required), startDate (required), previousEndDate (required), +1 more.

gsc_inspect_urlInspect a URL's index statusA
Read-onlyIdempotent

Returns Google's index status for a single URL: coverage verdict, last crawl time, Google-selected vs user-declared canonical, mobile usability, and rich-results verdict. QUOTA: 2,000 queries per day and 600 per minute PER PROPERTY. Do not loop this over a list of URLs without checking the quota budget first — inspect specific URLs the user asked about, and prefer gsc_search_analytics_query for anything aggregate. Read-only.

Inputs: siteUrl (required), inspectionUrl (required), languageCode.

gsc_list_sitemapsList submitted sitemapsA
Read-onlyIdempotent

Lists sitemaps submitted for a Search Console property, with last-downloaded time, warning and error counts, and per-type indexed counts. Useful for diagnosing indexing problems. Read-only.

Inputs: siteUrl (required), limit.

gsc_list_sitesList Search Console propertiesA
Read-onlyIdempotent

Lists every Search Console property the authenticated user can access, with their permission level. Use this FIRST to get the exact siteUrl string other Search Console tools need — the format is significant ('https://example.com/' for URL-prefix properties, 'sc-domain:example.com' for Domain properties). Read-only.

Inputs: limit.

gsc_search_analytics_queryQuery Search Console performance dataA
Read-onlyIdempotent

Returns clicks, impressions, CTR and average position from Search Console, grouped by the dimensions you choose. This is the primary SEO analysis tool. siteUrl must be the exact string from gsc_list_sites. Dates are YYYY-MM-DD only — relative forms like '28daysAgo' are NOT supported here (unlike the GA4 tools). Data lags roughly 2-3 days; use dataState='all' to include fresh partial data. Returns at most 25 rows by default while the API itself allows up to 25,000, so do not assume you are seeing everything — raise limit deliberately or narrow with filters. Page with startRow. Read-only.

Inputs: endDate (required), siteUrl (required), startDate (required), type, +6 more.

gtm_get_live_versionInspect the live GTM configurationA
Read-onlyIdempotent

Read the full currently published GTM version. Configuration is not proof a tag fired in a browser. May return a large container; choose a specific container.

Inputs: path (required).

gtm_list_accountsList Tag Manager accountsA
Read-onlyIdempotent

Lists every Google Tag Manager account the authenticated user can access. Use this FIRST to discover accountId, then gtm_list_containers, then gtm_list_workspaces. Read-only.

Inputs: limit, pageToken.

gtm_list_containersList Tag Manager containersA
Read-onlyIdempotent

Lists containers in a Tag Manager account. Call gtm_list_accounts first to get the accountId. NOTE the response has two different IDs: containerId is the numeric internal ID that every other GTM tool needs, while publicId is the GTM-XXXXXXX string shown in the UI. Pass the numeric one. Read-only.

Inputs: accountId (required), limit, pageToken.

gtm_list_tagsList tags in a workspaceA
Read-onlyIdempotent

Lists tags in a Tag Manager workspace with their type, firing triggers and parameters. Accepts a full workspace path or accountId + containerId + workspaceId. Parameters are condensed to key/value pairs for readability. Read-only.

Inputs: path, limit, accountId, pageToken, +2 more.

gtm_list_triggersList triggers in a workspaceA
Read-onlyIdempotent

Lists triggers in a Tag Manager workspace with their type and firing conditions. Accepts a full workspace path or accountId + containerId + workspaceId. Read-only.

Inputs: path, limit, accountId, pageToken, +2 more.

gtm_list_variablesList variables in a workspaceA
Read-onlyIdempotent

Lists user-defined variables in a Tag Manager workspace with their type and parameters. Note this returns user-defined variables only — built-in variables are a separate collection. Accepts a full workspace path or accountId + containerId + workspaceId. Read-only.

Inputs: path, limit, accountId, pageToken, +2 more.

gtm_list_workspacesList Tag Manager workspacesA
Read-onlyIdempotent

Lists workspaces in a container. Workspaces are the safe editing surface — all writes in this server operate on a workspace, never the live container. Accepts either a full container path or accountId + containerId (numeric internal ID). Read-only.

Inputs: path, limit, accountId, pageToken, +1 more.

gtm_preview_versionReview a GTM version before manual publishingA
Read-onlyIdempotent

READ ONLY. Compare a candidate version to the live version by stable entity IDs and configuration, including modified fields. This server cannot publish. Review full changes in Google Tag Manager before publishing there.

Inputs: versionPath (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 20 tools

    Disambiguation5/5

    Every tool is namespaced by Google product (ga4_, gsc_, gtm_) and targets a distinct resource or action; the only close pair, gsc_search_analytics_query and gsc_compare_periods, is clearly differentiated by purpose and output. The gtm_list_* family covers separate collections (accounts, containers, workspaces, tags, triggers, variables), so an agent should not confuse them.

    Naming Consistency4/5

    The set is uniformly snake_case and strongly patterned: ga4_/gsc_/gtm_ prefixes with list_ for collection reads and get_/run_/inspect_/compare_ for actions. Minor deviations such as gsc_search_analytics_query (noun-style) and gmcp_diagnostics (no action verb) keep it from a perfect score.

    Tool Count4/5

    Twenty tools is at the high end, but the number is reasonable for a server spanning three distinct Google products (GA4, Search Console, Tag Manager) plus diagnostics. Each cluster has enough tools to support real read-only workflows without feeling padded.

    Completeness4/5

    The read-only measurement surface is largely covered: GA4 has metadata/reporting/realtime/discovery, Search Console has search analytics/sitemaps/URL inspection, and GTM has account-through-entity listing plus live/version comparison. Minor gaps remain, such as no GTM built-in variable tool or GTM write/publish operations, but these appear to be intentionally out of scope.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to manage Google Tag Manager, Google Search Console, and Google Analytics (GA4) through unified access to tags, search performance data, URL inspection, sitemaps, and analytics reporting.
      7 npm
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI apps to plan, build, audit, and report on Google Ads, GA4, Search Console, and Tag Manager accounts through natural language. Accounts are read-only by default, and every change is validated in a preview, applied only after confirmation, logged, and reversible.
      4
      MIT