analytics-mcp-server
Allows read access to Google Analytics 4 (GA4) properties, enabling listing properties, running historical reports, and realtime reports for analytics data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@analytics-mcp-server what were my top pages last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 build2. Create a Google OAuth client (for GA4 + Search Console)
In Google Cloud Console, create/select a project.
Enable these APIs: Google Analytics Admin API, Google Analytics Data API, Search Console API.
Create an OAuth client with type Desktop app.
Copy
.env.exampleto.envand fill inGOOGLE_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 configured connections by name |
| List GA4 properties visible to a Google connection |
| Run a historical GA4 report (dimensions/metrics/date range) |
| Run a GA4 realtime (~last 30 min) report |
| List Search Console properties visible to a Google connection |
| Query clicks/impressions/CTR/position by dimension |
| Check a URL's index status |
| 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):
src/providers/<service>.ts— API client functions, no MCP-specific code.src/tools/<service>Tools.ts—registerToolcalls that wrap the provider functions.Register the new tools in
src/index.ts.If it needs OAuth, add a
run<Service>InteractiveAuthinsrc/auth/and anadd-<service>command inscripts/cli.ts, followinggoogleOAuth.ts. If it only needs an API key/token, just add it toConnectionStore'sConnectionunion 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 toolsclarity_get_insightsGet Microsoft Clarity InsightsARead-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 PropertiesARead-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 ReportARead-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 ReportARead-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 ConsoleARead-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 SitesARead-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 AnalyticsARead-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 ConnectionsARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Google Ads, Microsoft Advertising, GA4 and Search Console in Claude. Connect an ad account first.
Read-only access for your AI to Search Console, GA4, Google Ads, Meta Ads and your store's sales.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceConnects 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-

OQVA Marketing MCPofficial
AlicenseAqualityCmaintenanceConnect 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.351Apache 2.0- FlicenseAqualityDmaintenanceConnects Claude to Google Analytics 4 for querying website analytics via natural language, enabling traffic summaries, top pages, traffic sources, and user engagement.4-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-