MCP Pirsch MCP server

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.

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

PIRSCHDEFAULTDOMAINID is optional. When it is unset, every query tool requires domainId; the server never picks the first accessible domain. Use pirschlist_domains to discover IDs safely.

Optional PIRSCH_TIMEZONE supplies the default timezone for requests that do not explicitly include timezone.

Tools

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

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

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

Development

Shortened. The full README is on GitHub.