Skip to main content
Glama
analytics-mcp-server

analytics-mcp-server

by rakoo04

ga4-gsc-clarity-mcp-server

An MCP server that gives Claude read access to Google Analytics 4 (GA4), Google Search Console (GSC), and Microsoft Clarity — set up once, reusable from any project.

How it's scalable across projects

Connections (a Google account, a Clarity project token) are stored in ~/.analytics-mcp-server/, not inside this repo or any single project. You register the server once with claude mcp add --scope user, and every Claude Code project on your machine can then use list_connections and the ga4_* / gsc_* / clarity_* tools against any connection by name — no per-project setup, no re-authenticating for each new site or repo. Adding a new GA4 property, GSC site, or Clarity project later is just another npm run cli -- add-* call; no code changes needed.

Related MCP server: OQVA Marketing MCP

Important note on auth

Google's GA4 and Search Console APIs support OAuth, and this server uses it. Microsoft Clarity's Data Export API does not support OAuth — Clarity only issues per-project API tokens from its dashboard (Settings → Data Export), capped at 10 requests/day/token. Clarity connections in this server use that token, stored the same way as Google's refresh tokens. This is a limitation of Clarity's API, not a design choice here.

Setup

1. Install

npm install
npm run build

2. Create a Google OAuth client (for GA4 + Search Console)

  1. In Google Cloud Console, create/select a project.

  2. Enable these APIs: Google Analytics Admin API, Google Analytics Data API, Search Console API.

  3. Create an OAuth client with type Desktop app.

  4. Copy .env.example to .env and fill in GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET.

3. Add connections

Each connection is added once via the CLI, which handles secrets outside of any LLM conversation.

# Opens a browser for Google consent, stores a refresh token under the given name.
npm run cli -- add-google my-google         # both GA4 + GSC scopes
npm run cli -- add-google my-google --ga4   # GA4 only
npm run cli -- add-google my-google --gsc   # GSC only

# Stores a Clarity project token (generate one at https://clarity.microsoft.com,
# Settings > Data Export).
npm run cli -- add-clarity my-site --token <token> --label "My Site"

npm run cli -- list
npm run cli -- remove <name>

You can add as many named connections as you like — multiple Google accounts, multiple Clarity projects — and refer to any of them from any project by name.

4. Register the MCP server with Claude Code

claude mcp add --scope user analytics-mcp-server \
  --env GOOGLE_OAUTH_CLIENT_ID=<your-client-id> \
  --env GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret> \
  -- node /absolute/path/to/analytics-mcp-server/dist/src/index.js

--scope user makes it available in every project, which is the point — connections live outside any repo, so this only needs to be done once per machine.

Tools

Tool

Purpose

list_connections

List configured connections by name

ga4_list_properties

List GA4 properties visible to a Google connection

ga4_run_report

Run a historical GA4 report (dimensions/metrics/date range)

ga4_run_realtime_report

Run a GA4 realtime (~last 30 min) report

gsc_list_sites

List Search Console properties visible to a Google connection

gsc_query_search_analytics

Query clicks/impressions/CTR/position by dimension

gsc_inspect_url

Check a URL's index status

clarity_get_insights

Fetch Clarity traffic/engagement metrics (1-3 day window, cached hourly)

Adding another provider later

Follow the existing pattern to extend this to a new service (e.g. Meta Ads, another analytics tool):

  1. src/providers/<service>.ts — API client functions, no MCP-specific code.

  2. src/tools/<service>Tools.ts — registerTool calls that wrap the provider functions.

  3. Register the new tools in src/index.ts.

  4. If it needs OAuth, add a run<Service>InteractiveAuth in src/auth/ and an add-<service> command in scripts/cli.ts, following googleOAuth.ts. If it only needs an API key/token, just add it to ConnectionStore's Connection union and a CLI command, like Clarity.

Development

npm run dev     # run the server with auto-reload (tsx)
npm run build   # type-check + compile to dist/

Available Tools

8 tools
clarity_get_insightsGet Microsoft Clarity InsightsA
Read-onlyIdempotent

Fetch Microsoft Clarity's traffic and engagement metrics (sessions, bots, engagement time, scroll depth, rage clicks, quick backs, dead clicks, script errors, and more) for a connected Clarity project, optionally broken down by up to 3 dimensions.

Note: Clarity connections authenticate with a per-project API token generated in the Clarity dashboard (Settings > Data Export), not OAuth — Clarity's Data Export API does not support OAuth. Each token is capped at 10 requests/day; this tool caches results for 1 hour to help stay under that limit.

Args:

  • connection (string): Name of a configured Clarity connection

  • num_of_days (1 | 2 | 3): How many trailing days of data to fetch (Clarity only supports 1-3)

  • dimensions (string[], optional): Up to 3 of: Browser, Device, Country, OS, Source, Medium, Campaign, Channel, URL, PageTitle. Omit for totals with no breakdown.

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns raw per-metric breakdowns as reported by Clarity, e.g. one entry per metric name ("Traffic", "EngagementTime", "ScrollDepth", "DeadClickCount", ...) each with an "information" array of rows for the requested dimension breakdown.

Use when: "How is Clarity engagement trending by device over the last 3 days?" -> dimensions=["Device"] Don't use when: You need historical data beyond 3 days (Clarity's export API doesn't support that; use the Clarity dashboard/UI instead).

Error Handling:

  • Returns "Clarity API rate limit reached" if the project's 10-requests/day cap is hit; wait and retry, or reuse a cached result.

Inputs: connection (required), dimensions, num_of_days, response_format.

ga4_list_propertiesList GA4 PropertiesA
Read-onlyIdempotent

List every Google Analytics 4 property the connected Google account can access.

Args:

  • connection (string): Name of a configured Google connection (see list_connections)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns property IDs needed by ga4_run_report and ga4_run_realtime_report.

Use when: "What GA4 properties do I have access to?" or to look up a property_id by site name before running a report.

Inputs: connection (required), response_format.

ga4_run_realtime_reportRun GA4 Realtime ReportA
Read-onlyIdempotent

Run a Google Analytics 4 realtime report, covering roughly the last 30 minutes of activity.

Args:

  • connection (string): Name of a configured Google connection

  • property_id (string): GA4 property ID (from ga4_list_properties)

  • dimensions (string[]): Realtime dimension API names, e.g. ["country", "unifiedScreenName"]

  • metrics (string[]): Realtime metric API names, e.g. ["activeUsers", "screenPageViews"]

  • limit (number): Max rows to return (default 20, max 250)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Note: only a subset of GA4 dimensions/metrics support realtime reporting — see https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema

Use when: "How many people are on the site right now?" or "What pages are active users viewing at this moment?" Don't use when: You need historical trends (use ga4_run_report instead).

Inputs: metrics (required), connection (required), dimensions (required), property_id (required), +2 more.

ga4_run_reportRun GA4 ReportA
Read-onlyIdempotent

Run a Google Analytics 4 report over a historical date range, similar to a custom report in the GA4 UI.

Args:

  • connection (string): Name of a configured Google connection

  • property_id (string): GA4 property ID (from ga4_list_properties), digits only, no "properties/" prefix

  • start_date, end_date (string): YYYY-MM-DD, or a GA4 relative keyword such as 'today', 'yesterday', or 'NdaysAgo' (e.g. '28daysAgo')

  • dimensions (string[]): GA4 dimension API names, e.g. ["date", "country", "sessionDefaultChannelGroup"]

  • metrics (string[]): GA4 metric API names, e.g. ["activeUsers", "sessions", "conversions"]

  • limit (number): Max rows to return (default 50, max 1000)

  • offset (number): Rows to skip, for pagination (default 0)

  • dimension_filter_field, dimension_filter_value (string, optional): Restrict to rows where this dimension exactly equals this value

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Full dimension/metric reference: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema

Returns: For JSON: { "dimensionHeaders": string[], "metricHeaders": string[], "rows": object[], "rowCount": number }

Use when: "How many sessions did we get last week by channel?" -> dimensions=["sessionDefaultChannelGroup"], metrics=["sessions"], start_date/end_date set accordingly. Don't use when: You need live/last-30-minutes data (use ga4_run_realtime_report instead).

Error Handling:

  • Returns an error naming the invalid dimension/metric if GA4 rejects the combination (not every dimension and metric can be combined).

Inputs: metrics (required), end_date (required), connection (required), dimensions (required), +7 more.

gsc_inspect_urlInspect URL in Search ConsoleA
Read-onlyIdempotent

Check a single URL's Google index status via the Search Console URL Inspection API: whether it's indexed, when it was last crawled, and why it might not be indexed.

Args:

  • connection (string): Name of a configured Google connection

  • site_url (string): Exact site URL from gsc_list_sites that owns inspection_url

  • inspection_url (string): Full URL to inspect, must belong to site_url

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Use when: "Why isn't this page showing up in Google?" or "Is this URL indexed?" Don't use when: You need aggregate query/click data (use gsc_query_search_analytics instead).

Inputs: site_url (required), connection (required), inspection_url (required), response_format.

gsc_list_sitesList Search Console SitesA
Read-onlyIdempotent

List every Search Console property (site or domain) the connected Google account can access.

Args:

  • connection (string): Name of a configured Google connection

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns site URLs (e.g. "https://example.com/" or "sc-domain:example.com") needed by gsc_query_search_analytics and gsc_inspect_url.

Use when: "What Search Console properties do I have access to?"

Inputs: connection (required), response_format.

gsc_query_search_analyticsQuery Search Console Search AnalyticsA
Read-onlyIdempotent

Query Google Search Console's Search Analytics data: clicks, impressions, CTR, and average position, broken down by dimensions.

Args:

  • connection (string): Name of a configured Google connection

  • site_url (string): Exact site URL from gsc_list_sites (e.g. "sc-domain:example.com")

  • start_date, end_date (string): YYYY-MM-DD. Search Console data typically lags 2-3 days behind today.

  • dimensions (string[]): Any of "query", "page", "country", "device", "date", "searchAppearance" (default: ["query"])

  • row_limit (number): Max rows (default 25, max 25000)

  • start_row (number): Rows to skip, for pagination (default 0)

  • search_type ('web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews'): default 'web'

  • filter_dimension, filter_operator, filter_value: Optional single filter, e.g. filter_dimension="page", filter_operator="contains", filter_value="/blog/"

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON: { "rows": [{ "keys": string[], "clicks": number, "impressions": number, "ctr": number, "position": number }] } "keys" holds one value per requested dimension, in the same order as the "dimensions" argument.

Use when: "What are our top search queries this month?" -> dimensions=["query"] Use when: "Which pages get the most impressions but low CTR?" -> dimensions=["page"], sort client-side on the returned rows. Don't use when: You need page indexing status (use gsc_inspect_url instead).

Inputs: end_date (required), site_url (required), connection (required), start_date (required), +8 more.

list_connectionsList Analytics ConnectionsA
Read-onlyIdempotent

List every configured connection (Google account or Clarity project) available to this MCP server.

Connections are set up once, outside of the LLM conversation, via the CLI (npm run cli -- add-google <name> or npm run cli -- add-clarity <name> --token <token>) and are stored in ~/.analytics-mcp-server, independent of any single project — the same connection can be reused across any project by referring to it by name.

Every other tool in this server takes a "connection" argument matching one of the names returned here.

Args:

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "connections": [ { "name": string, "type": "google" | "clarity", "label": string, "createdAt": string } ] }

Use when: "What analytics connections do I have set up?" or before calling any ga4_/gsc_/clarity_ tool if the connection name is unknown.

Inputs: response_format.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct service and action combination: connection listing, GA4 property listing, historical GA4 reports, GA4 realtime reports, GSC site listing, URL inspection, search analytics queries, and Clarity insights. The only near-overlap (ga4_run_report vs ga4_run_realtime_report) is clearly disambiguated by time range and explicit 'Don't use when' guidance.

    Naming Consistency4/5

    Most tools follow a consistent service-prefix_verb_noun pattern (ga4_list_properties, ga4_run_report, gsc_query_search_analytics, clarity_get_insights). The bare list_connections is a minor deviation, and verbs vary across services (run vs query vs get), but the pattern is still predictable and readable.

    Tool Count5/5

    Eight tools is well-scoped for an analytics MCP server covering three distinct platforms (GA4, GSC, Clarity). Each tool serves a concrete, necessary purpose without redundancy, and the count stays comfortably within the ideal range.

    Completeness4/5

    The server covers the core read/report lifecycle for each integration: property/site discovery, historical and realtime GA4 reports, GSC search analytics and URL inspection, and Clarity insights. Minor gaps exist (no GA4 dimension/metric metadata lookup, no GSC sitemap functionality), but agents can accomplish primary analytics workflows without dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects Claude AI to Google Search Console with OAuth 2.0 authentication, enabling users to analyze search performance, inspect URLs, manage sitemaps, and export analytics data through natural language conversations.
      2
      -
    • A
      license
      A
      quality
      C
      maintenance
      Connect Claude to your marketing data from Google and Meta, enabling read and write operations on Search Console, Analytics, Tag Manager, Business Profile, and Meta platforms.
      35
      1
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Connects Claude to Google Analytics 4 for querying website analytics via natural language, enabling traffic summaries, top pages, traffic sources, and user engagement.
      4
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables users to securely connect Claude to their own Google Search Console data, providing custom SEO analyses such as quick wins, content decay, and cannibalization, plus optional BigQuery bulk export, with per-user token scoping and read-only tools.
      -