Skip to main content
Glama
verygoodplugins

Pirsch Analytics MCP Server

Pirsch MCP Server

npm

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

pirsch_list_domains

Lists only id, hostname, display name, and timezone.

pirsch_query_statistics

Reads one documented v1 metric, with dates and filters.

pirsch_list_filter_options

Lists allowed values for a documented filter dimension.

pirsch_compare_periods

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

pirsch_overview, pirsch_total, pirsch_pages, pirsch_events, and other statistic tools

pirsch_query_statistics with metric

pirsch_utm

pirsch_query_statistics with one of the utm_* metrics

pirsch_compare

pirsch_compare_periods

Domain discovery

pirsch_list_domains

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 json

The 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 tools
pirsch_compare_periodsCompare Pirsch periodsA
Read-only

Compare Pirsch totals and visitor series for a named or explicitly supplied pair of periods.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNo
cityNo
fromNo
pathNo
sortNo
tagsNo
eventNo
limitNo
scaleNo
startNo
offsetNo
periodNo
regionNo
searchNo
toTimeNo
browserNo
channelNo
countryNo
keywordNo
patternNo
utmTermNo
domainIdNo
exitPathNo
fromTimeNo
hostnameNo
languageNo
platformNo
referrerNo
timezoneNo
compareToNo
directionNo
entryPathNo
sessionIdNo
utmMediumNo
utmSourceNo
visitorIdNo
utmContentNo
compareFromNo
screenClassNo
utmCampaignNo
eventMetaKeyNo
includeTitleNo
referrerNameNo
customMetricKeyNo
operatingSystemNo
customMetricTypeNo
includeAverageTimeOnPageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
seriesYes
totalsYes
currentYes
domainIdYes
previousYes

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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 domainsA
Read-only

List safe summaries of domains available to the configured read-only Pirsch OAuth client.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
domainsYes

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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 optionsC
Read-only

List supported values for one documented Pirsch Analytics API v1 filter dimension.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNo
cityNo
fromNo
pathNo
sortNo
tagsNo
eventNo
limitNo
scaleNo
startNo
offsetNo
optionYes
regionNo
searchNo
toTimeNo
browserNo
channelNo
countryNo
keywordNo
patternNo
utmTermNo
domainIdNo
exitPathNo
fromTimeNo
hostnameNo
languageNo
platformNo
referrerNo
timezoneNo
directionNo
entryPathNo
sessionIdNo
utmMediumNo
utmSourceNo
visitorIdNo
utmContentNo
screenClassNo
utmCampaignNo
eventMetaKeyNo
includeTitleNo
referrerNameNo
customMetricKeyNo
operatingSystemNo
customMetricTypeNo
includeAverageTimeOnPageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYes
optionYes
domainIdYes

TDQS

C2.8/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness1/5

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.

Parameters1/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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 analyticsB
Read-only

Read one documented Pirsch Analytics API v1 metric for an explicitly selected domain and filter.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNo
cityNo
fromNo
pathNo
sortNo
tagsNo
eventNo
limitNo
scaleNo
startNo
metricYes
offsetNo
regionNo
searchNo
toTimeNo
browserNo
channelNo
countryNo
keywordNo
patternNo
utmTermNo
domainIdNo
exitPathNo
fromTimeNo
hostnameNo
languageNo
platformNo
referrerNo
timezoneNo
directionNo
entryPathNo
sessionIdNo
utmMediumNo
utmSourceNo
visitorIdNo
utmContentNo
screenClassNo
utmCampaignNo
eventMetaKeyNo
includeTitleNo
referrerNameNo
customMetricKeyNo
operatingSystemNo
customMetricTypeNo
includeAverageTimeOnPageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYes
metricYes
domainIdYes

TDQS

B3.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters1/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 20 tool updatesv0.1.3
    • Removedpirsch_active
    • Removedpirsch_compare
    • Addedpirsch_compare_periods
    • Removedpirsch_entry_pages
    • Removedpirsch_event_pages
    • Removedpirsch_events
    • Removedpirsch_exit_pages
    • Removedpirsch_goals
    • Removedpirsch_growth
    • Changedpirsch_list_domains3 fields changed
      • addedInput schema / $schema
        Added value: +"https://json-schema.org/draft/2020-12/schema"
      • removedInput schema / properties / search
        Removed value: -{
        -  "type": "string"
        -}
      • changedOutput 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"
        +}
    • Addedpirsch_list_filter_options
    • Removedpirsch_overview
    • Removedpirsch_pages
    • Addedpirsch_query_statistics
    • Removedpirsch_referrers
    • Removedpirsch_session_details
    • Removedpirsch_sessions
    • Removedpirsch_total
    • Removedpirsch_utm
    • Removedpirsch_visitors
  2. 17 tool updatesv0.1.2
    • First observedpirsch_active
    • First observedpirsch_compare
    • First observedpirsch_entry_pages
    • First observedpirsch_event_pages
    • First observedpirsch_events
    • First observedpirsch_exit_pages
    • First observedpirsch_goals
    • First observedpirsch_growth
    • First observedpirsch_list_domains
    • First observedpirsch_overview
    • First observedpirsch_pages
    • First observedpirsch_referrers
    • First observedpirsch_session_details
    • First observedpirsch_sessions
    • First observedpirsch_total
    • First observedpirsch_utm
    • First observedpirsch_visitors

TDQS

A3.7/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

Four tools is well-scoped for a read-only analytics server. Each tool covers a necessary high-level operation without unnecessary bloat or redundancy.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

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

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying Plausible Analytics data for website statistics, traffic, engagement, and conversions through natural language, with support for filters, dimensions, and time-series.
    6
    -
  • A
    license
    B
    quality
    D
    maintenance
    Enables natural language interaction with Plausible Analytics data to query traffic, visitors, engagement, and more using conversational questions.
    4
    1
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    MCP 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.
    8
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Exposes Rybbit Analytics as MCP tools for querying site traffic, page views, visitor sessions, and live visitor counts through natural language.
    9
    MIT

Latest Blog Posts

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