MCP Pirsch

io.github.verygoodpluginsPublished by GitHub account verygoodpluginsv0.2.0Updated Oct 24, 2026

Pirsch Analytics with natural language queries and trend analysis

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Read-only access to Pirsch Analytics, letting an assistant query website statistics, filter options, and period comparisons in natural language.

What you can do
Wraps the Pirsch Analytics API v1 with four read-only tools: pirsch_list_domains lists accessible domains with id, hostname, display name, and timezone; pirsch_query_statistics reads one documented metric with dates and filters; pirsch_list_filter_options lists allowed values for a filter dimension; and pirsch_compare_periods compares totals and visitor series across two periods. Results come back as structured content plus an equivalent JSON text block.
When to use it
Useful when you want an assistant to answer questions about Pirsch website traffic, such as page views, visitors, goals, events, UTM campaigns, or period-over-period trends, without opening the Pirsch dashboard.
Requirements
Node.js 22.19.0 or later, run locally via npx. A Pirsch OAuth API client with read access is required, supplied through the environment variables PIRSCH_CLIENT_ID and PIRSCH_CLIENT_SECRET. PIRSCH_DEFAULT_DOMAIN_ID and PIRSCH_TIMEZONE are optional; without a default domain ID, each query tool needs an explicit domainId.
Before you install
Credentials are passed as environment variables PIRSCH_CLIENT_ID and PIRSCH_CLIENT_SECRET; a read-only OAuth client is recommended rather than a write-only access key. All tools are read-only and do not modify Pirsch data. Queries send analytics requests to the Pirsch API, and error responses are designed not to expose credentials or raw upstream bodies.

Installation

In SourceWeft

  1. Open MCP Pirsch in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

Configure

json
{  "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

ToolPurpose
pirsch_list_domainsLists only id, hostname, display name, and timezone.
pirsch_query_statisticsReads one documented v1 metric, with dates and filters.
pirsch_list_filter_optionsLists allowed values for a documented filter dimension.
pirsch_compare_periodsCompares 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:

json
{  "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:

json
{  "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 toolsReplacement
pirsch_overview, pirsch_total, pirsch_pages, pirsch_events, and other statistic toolspirsch_query_statistics with metric
pirsch_utmpirsch_query_statistics with one of the utm_* metrics
pirsch_comparepirsch_compare_periods
Domain discoverypirsch_list_domains

Input names are now camel-case and flat (domainId, compareFrom, eventMetaKey), not domain_id, nested filter, or compatibility aliases.

Development

bash
npm installnpm run typechecknpm run lintnpm testnpm run buildnpx -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.

Source: README.md at commit 4c15bb0

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts