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 "Install 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 Servershow 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 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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| city | No | ||
| from | No | ||
| path | No | ||
| sort | No | ||
| tags | No | ||
| event | No | ||
| limit | No | ||
| scale | No | ||
| start | No | ||
| offset | No | ||
| period | No | ||
| region | No | ||
| search | No | ||
| toTime | No | ||
| browser | No | ||
| channel | No | ||
| country | No | ||
| keyword | No | ||
| pattern | No | ||
| utmTerm | No | ||
| domainId | No | ||
| exitPath | No | ||
| fromTime | No | ||
| hostname | No | ||
| language | No | ||
| platform | No | ||
| referrer | No | ||
| timezone | No | ||
| compareTo | No | ||
| direction | No | ||
| entryPath | No | ||
| sessionId | No | ||
| utmMedium | No | ||
| utmSource | No | ||
| visitorId | No | ||
| utmContent | No | ||
| compareFrom | No | ||
| screenClass | No | ||
| utmCampaign | No | ||
| eventMetaKey | No | ||
| includeTitle | No | ||
| referrerName | No | ||
| customMetricKey | No | ||
| operatingSystem | No | ||
| customMetricType | No | ||
| includeAverageTimeOnPage | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| series | Yes | |
| totals | Yes | |
| current | Yes | |
| domainId | Yes | |
| previous | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful non-obvious context — that the tool produces both aggregate totals and a visitor series, and that periods can be supplied two different ways — but it does not disclose how the comparison is presented (deltas vs side-by-side) or how named and explicit periods interact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 15-word sentence that front-loads the verb and resource and compresses both period-specification modes into one phrase. There is no filler, redundancy, or repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema and safety annotations cover return values and side-effect profile, the tool is highly complex (47 parameters, 0 required, 0% schema coverage) and the one-sentence description covers only the core concept. An agent still cannot determine which parameters form the primary versus comparison period pair, how 'period' interacts with explicit date ranges, or what most optional parameters mean, so the description is insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage across 47 parameters, the description must carry semantic weight. It contributes the central concept that two periods are involved and can be expressed by name (mapping to 'period') or explicitly (mapping to from/to plus compareFrom/compareTo). Yet it never names these parameters or clarifies the remaining filter/dimension parameters, leaving the agent to infer their roles from their names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Compare'), a concrete resource ('Pirsch totals and visitor series'), and a scope ('a named or explicitly supplied pair of periods'), going well beyond the title. It also implicitly differentiates from siblings like pirsch_list_domains (listing), pirsch_query_statistics (single-scope querying), and pirsch_list_filter_options (enumerating options), since comparison is a distinct operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied rather than stated: invoke this tool when a two-period comparison is needed, and choose between a 'named' period or an explicit date pair. However, it never explicitly routes away from pirsch_query_statistics for single-period needs or states when not to use this tool, leaving the agent to infer the decision boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pirsch_list_domainsList Pirsch domainsARead-only
List safe summaries of domains available to the configured read-only Pirsch OAuth client.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| domains | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false, so the description's 'safe summaries' and 'read-only OAuth client' reinforce but don't heavily extend that. It adds some context about the nature of the output (safe summaries) and authentication, but doesn't disclose behaviors like pagination, rate limits, or output format beyond what the schema already provides. This is consistent with the bar set by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that front-loads the primary action and resource. It is concise with no wasted words, and all information is relevant to the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description doesn't need to detail return structure. It mentions the OAuth client and 'safe summaries,' which provides sufficient context for an agent to know what it will get. Minor lack of detail about what 'safe' means is acceptable since the output schema can clarify.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description doesn't need to add parameter meaning; 'safe summaries' is the only behavioral nuance and is not tied to any parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('safe summaries of domains'), and it distinguishes itself from siblings like pirsch_query_statistics by focusing on domain listing. The phrase 'configured read-only Pirsch OAuth client' adds precision about the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you need to list domains available to the configured client—but does not explicitly name alternatives or exclusions. However, the context is clear and the sibling tools (statistics, filter options, compare periods) are obviously different in purpose, so it provides adequate guidance without explicit 'when-not-to-use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pirsch_list_filter_optionsList Pirsch filter optionsCRead-only
List supported values for one documented Pirsch Analytics API v1 filter dimension.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| city | No | ||
| from | No | ||
| path | No | ||
| sort | No | ||
| tags | No | ||
| event | No | ||
| limit | No | ||
| scale | No | ||
| start | No | ||
| offset | No | ||
| option | Yes | ||
| region | No | ||
| search | No | ||
| toTime | No | ||
| browser | No | ||
| channel | No | ||
| country | No | ||
| keyword | No | ||
| pattern | No | ||
| utmTerm | No | ||
| domainId | No | ||
| exitPath | No | ||
| fromTime | No | ||
| hostname | No | ||
| language | No | ||
| platform | No | ||
| referrer | No | ||
| timezone | No | ||
| direction | No | ||
| entryPath | No | ||
| sessionId | No | ||
| utmMedium | No | ||
| utmSource | No | ||
| visitorId | No | ||
| utmContent | No | ||
| screenClass | No | ||
| utmCampaign | No | ||
| eventMetaKey | No | ||
| includeTitle | No | ||
| referrerName | No | ||
| customMetricKey | No | ||
| operatingSystem | No | ||
| customMetricType | No | ||
| includeAverageTimeOnPage | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| option | Yes | |
| domainId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety and mutation semantics. However, the description adds no behavioral context beyond a bare 'list' operation. It does not describe the return format (e.g., an array of strings), any pagination behavior, or that the results are dependent on the 'option' parameter. The description provides minimal value over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundancy. It front-loads the core purpose and uses precise terminology. This is appropriately concise for a simple listing operation, despite lacking depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (45 parameters, 5 enums, no output schema shown), the description is severely under-specified. It does not explain how to select among the many optional parameters, nor does it mention that different 'option' values may accept different filters. An agent would struggle to call this tool correctly without additional documentation or schema exploration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% – the description explains none of the 45 parameters, not even the required 'option'. The description does not clarify how to use the additional filter parameters (e.g., country, city, page) or that they are contextual depending on the chosen option. An agent cannot infer parameter purpose from the description, which is a critical gap for a tool with dozens of properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'List supported values for one documented Pirsch Analytics API v1 filter dimension.' It clearly identifies the verb (list), the resource (supported values for a filter dimension), and the domain (Pirsch Analytics API v1). This distinguishes it from sibling tools that operate on domains, statistics, or period comparisons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention that it should be used to fetch allowed values before constructing a filter query, nor does it contrast with pirsch_query_statistics or pirsch_compare_periods. The agent is left to infer the use case from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pirsch_query_statisticsQuery Pirsch analyticsBRead-only
Read one documented Pirsch Analytics API v1 metric for an explicitly selected domain and filter.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| city | No | ||
| from | No | ||
| path | No | ||
| sort | No | ||
| tags | No | ||
| event | No | ||
| limit | No | ||
| scale | No | ||
| start | No | ||
| metric | Yes | ||
| offset | No | ||
| region | No | ||
| search | No | ||
| toTime | No | ||
| browser | No | ||
| channel | No | ||
| country | No | ||
| keyword | No | ||
| pattern | No | ||
| utmTerm | No | ||
| domainId | No | ||
| exitPath | No | ||
| fromTime | No | ||
| hostname | No | ||
| language | No | ||
| platform | No | ||
| referrer | No | ||
| timezone | No | ||
| direction | No | ||
| entryPath | No | ||
| sessionId | No | ||
| utmMedium | No | ||
| utmSource | No | ||
| visitorId | No | ||
| utmContent | No | ||
| screenClass | No | ||
| utmCampaign | No | ||
| eventMetaKey | No | ||
| includeTitle | No | ||
| referrerName | No | ||
| customMetricKey | No | ||
| operatingSystem | No | ||
| customMetricType | No | ||
| includeAverageTimeOnPage | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| metric | Yes | |
| domainId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that the metric must be documented and the domain explicitly selected, which is useful scope context. It does not describe pagination, rate limits, or error behavior, but with annotations covering safety, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, front-loading the action 'Read'. It is concise, clear, and every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 45 parameters and zero schema descriptions, the description is severely under-specified. It does not explain the relationship to sibling tools, the role of domainId despite being optional, or how to combine filters. The output schema and annotations reduce some burden, but an agent would need external documentation to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 45 parameters, and the description fails to compensate. It does not explain how to specify the metric, how to select the domain via domainId, which parameters act as filters, or any mutual exclusivity. The only hint is 'explicitly selected domain', which is vague and not mapped to the schema (domainId is optional, only metric is required).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Read' and clearly identifies the resource as a Pirsch Analytics API v1 metric, with constraints that it handles one metric for an explicitly selected domain and filter. This distinguishes it from siblings like pirsch_list_domains and pirsch_compare_periods, though it does not name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for single-metric queries by saying 'one documented metric' and 'explicitly selected domain', which hints at prerequisites like selecting a domain and providing filters. However, it does not explicitly state when to use this tool over pirsch_list_domains or pirsch_compare_periods, nor does it mention needing domain IDs from list_domains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
20 tool updates
v0.1.3- Removed
pirsch_active - Removed
pirsch_compare - Added
pirsch_compare_periods - Removed
pirsch_entry_pages - Removed
pirsch_event_pages - Removed
pirsch_events - Removed
pirsch_exit_pages - Removed
pirsch_goals - Removed
pirsch_growth - Changed
pirsch_list_domains3 fields changed- added
Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema" - removed
Input schema / properties / searchRemoved value: -{ - "type": "string" -} - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "domains": { + "items": { + "additionalProperties": false, + "properties": { + "displayName": { + "type": "string" + }, + "hostname": { + "type": "string" + }, + "id": { + "type": "string" + }, + "timezone": { + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "domains" + ], + "type": "object" +}
- Added
pirsch_list_filter_options - Removed
pirsch_overview - Removed
pirsch_pages - Added
pirsch_query_statistics - Removed
pirsch_referrers - Removed
pirsch_session_details - Removed
pirsch_sessions - Removed
pirsch_total - Removed
pirsch_utm - Removed
pirsch_visitors
17 tool updates
v0.1.2- First observed
pirsch_active - First observed
pirsch_compare - First observed
pirsch_entry_pages - First observed
pirsch_event_pages - First observed
pirsch_events - First observed
pirsch_exit_pages - First observed
pirsch_goals - First observed
pirsch_growth - First observed
pirsch_list_domains - First observed
pirsch_overview - First observed
pirsch_pages - First observed
pirsch_referrers - First observed
pirsch_session_details - First observed
pirsch_sessions - First observed
pirsch_total - First observed
pirsch_utm - First observed
pirsch_visitors
TDQS
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
Analytics your AI agent can actually use. Track, experiment, and optimize via MCP.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying Plausible Analytics data for website statistics, traffic, engagement, and conversions through natural language, with support for filters, dimensions, and time-series.6-
- AlicenseBqualityDmaintenanceEnables natural language interaction with Plausible Analytics data to query traffic, visitors, engagement, and more using conversational questions.41MIT
- AlicenseAqualityCmaintenanceMCP 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
- AlicenseAqualityCmaintenanceExposes Rybbit Analytics as MCP tools for querying site traffic, page views, visitor sessions, and live visitor counts through natural language.9MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/verygoodplugins/mcp-pirsch'
If you have feedback or need assistance with the MCP directory API, please join our Discord server