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.

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.

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).

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).

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?"

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).

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).

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.