Pirsch Analytics MCP Server
This is a read-only MCP server for querying Pirsch Analytics API v1, offering four tools to list domains, query statistics, list filter options, and compare periods.
List domains:
pirsch_list_domainsreturns safe summaries (id, hostname, displayName, timezone) of domains accessible to the configured read-only OAuth client.Query statistics:
pirsch_query_statisticsreads a single documented metric (e.g., pages, events, sessions, UTM, countries, browsers) for a specified domain and optional flat camel-case filters, dates, limit (1–100), sorting, and timezone.List filter options:
pirsch_list_filter_optionslists supported values for a filter dimension (e.g., hostname, page, country, browser, UTM fields, tags) to help construct valid queries.Compare periods:
pirsch_compare_periodscompares actual totals and visitor series between a named period (today, yesterday, week, etc.) or explicit date ranges, including change percentages.Read-only and safe: All tools are annotated as read-only, never expose credentials or raw upstream error bodies, and require explicit domain selection unless a default is configured.
Structured output: Each tool returns both
structuredContentmatching its output schema and equivalent JSON text.
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., "@Pirsch Analytics MCP Server show me the total visitors for the last 30 days"
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.
Pirsch MCP Server
A focused, read-only Model Context Protocol server for Pirsch Analytics API v1. It uses MCP SDK v2 and returns both structured results and JSON text for every successful tool call.
Requirements
Node.js 22.19.0 or later
A Pirsch OAuth API client with read access. Do not use a write-only access key.
Related MCP server: plausible-whenever-mcp
Configure
{
"mcpServers": {
"pirsch": {
"command": "npx",
"args": ["-y", "@verygoodplugins/mcp-pirsch@latest"],
"env": {
"PIRSCH_CLIENT_ID": "your-read-only-oauth-client-id",
"PIRSCH_CLIENT_SECRET": "your-oauth-client-secret",
"PIRSCH_DEFAULT_DOMAIN_ID": "optional-default-domain-id"
}
}
}
}PIRSCH_DEFAULT_DOMAIN_ID is optional. When it is unset, every query tool requires domainId; the server never picks the first accessible domain. Use pirsch_list_domains to discover IDs safely.
Optional PIRSCH_TIMEZONE supplies the default timezone for requests that do not explicitly include timezone.
Tools
Tool | Purpose |
| Lists only |
| Reads one documented v1 metric, with dates and filters. |
| Lists allowed values for a documented filter dimension. |
| Compares actual totals and visitor series for two periods. |
All tools are read-only. They return structuredContent matching their output schema as well as an equivalent JSON text block. Input or API failures use MCP isError: true and do not expose credentials or raw upstream bodies.
Querying statistics
pirsch_query_statistics accepts a metric, optional domainId, and flat camel-case filters. Most metrics require ISO dates:
{
"metric": "pages",
"domainId": "your-domain-id",
"from": "2026-08-01",
"to": "2026-08-23",
"limit": 20,
"sort": "visitors",
"direction": "desc"
}The server maps public camel-case fields such as eventMetaKey, entryPath, operatingSystem, and utmCampaign to Pirsch's documented API-v1 parameter names. limit is constrained to 1–100 and active visitor start to 0–3600 seconds.
Metrics include totals, visitors, pages and entry/exit pages, session and page duration, goals, events and event metadata, growth, active visitors, time breakdowns, acquisition, browser/device, geographic, UTM, tags, keywords, funnels, sessions, and session details. session_details requires both visitorId and sessionId; event-specific metrics require event.
Comparing periods
Provide a named period (today, yesterday, week, lastWeek, month, or lastMonth) or both explicit date pairs:
{
"domainId": "your-domain-id",
"from": "2026-08-01",
"to": "2026-08-07",
"compareFrom": "2026-07-25",
"compareTo": "2026-07-31",
"scale": "day"
}The response compares /statistics/total and retains the two /statistics/visitor series; it does not estimate totals by summing charts.
1.0 migration
Version 1.0 intentionally replaces the former 17-tool interface. There are no default aliases because aliases would keep unsafe domain-selection and ambiguous input behavior alive.
Previous tools | Replacement |
|
|
|
|
|
|
Domain discovery |
|
Input names are now camel-case and flat (domainId, compareFrom, eventMetaKey), not domain_id, nested filter, or compatibility aliases.
Development
npm install
npm run typecheck
npm run lint
npm test
npm run build
npx -y @modelcontextprotocol/inspector@latest --cli node dist/index.js --method tools/list --format jsonThe release workflow publishes to npm with trusted publishing and then publishes the same tagged manifest to the MCP Registry through GitHub OIDC. Local development and CI never publish anything.
Support
For bugs and feature requests, open an issue in this repository. Pirsch questions are best answered through the Pirsch documentation; package support is maintained by Very Good Plugins.
Built with 🧡 by Very Good Plugins.
Available Tools
4 toolspirsch_compare_periodsCompare Pirsch periodsARead-only
Compare Pirsch totals and visitor series for a named or explicitly supplied pair of periods.
Inputs: to, city, from, path, +43 more. Returns: series, totals, current, domainId, +1 more
pirsch_list_domainsList Pirsch domainsARead-only
List safe summaries of domains available to the configured read-only Pirsch OAuth client.
Inputs: no named parameters. Returns: domains
pirsch_list_filter_optionsList Pirsch filter optionsCRead-only
List supported values for one documented Pirsch Analytics API v1 filter dimension.
Inputs: option (required), to, city, from, +41 more. Returns: data, option, domainId
pirsch_query_statisticsQuery Pirsch analyticsBRead-only
Read one documented Pirsch Analytics API v1 metric for an explicitly selected domain and filter.
Inputs: metric (required), to, city, from, +41 more. Returns: data, metric, domainId
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct concern: listing domains, querying a metric, enumerating filter options, and comparing periods. There is no overlap or ambiguity between them.
All tools follow a consistent 'pirsch_verb_noun' pattern (list_domains, query_statistics, list_filter_options, compare_periods). The naming style is uniform and predictable.
Four tools is well-scoped for a read-only analytics server. Each tool covers a necessary high-level operation without unnecessary bloat or redundancy.
The set covers the core read-only needs: domain discovery, metric querying, filter exploration, and period comparison. A minor gap is the lack of a more comprehensive report endpoint, but the available tools can be combined to cover most scenarios.
Maintenance
Related MCP Connectors
Ask your website analytics in plain language and set up funnels, features and dashboards.
Ask your web and product analytics: traffic, funnels, goals, revenue and sessions.
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
Ask an assistant about your website traffic. Privacy-first web analytics, no cookies. OAuth.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables natural language interaction with Plausible Analytics data to query traffic, visitors, engagement, and more using conversational questions.41MIT
- AlicenseAqualityDmaintenanceMCP server that provides read access to Plausible Analytics data with natural-language date resolution, enabling users to query analytics like 'yesterday' or 'last week' without needing to know exact date formats.8MIT
- AlicenseAqualityDmaintenanceExposes Rybbit Analytics as MCP tools for querying site traffic, page views, visitor sessions, and live visitor counts through natural language.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying Google Analytics 4 data using natural language through MCP clients like Claude and Cursor, supporting 200+ dimensions and metrics for traffic, user behavior, and e-commerce analysis.MIT