{
  "markdown": "# Pirsch MCP Server\n\n[![npm](https://img.shields.io/npm/v/@verygoodplugins/mcp-pirsch)](https://www.npmjs.com/package/@verygoodplugins/mcp-pirsch)\n\nA focused, read-only [Model Context Protocol](https://modelcontextprotocol.io) server for [Pirsch Analytics API v1](https://docs.pirsch.io/api-sdks/api-v1). It uses MCP SDK v2 and returns both structured results and JSON text for every successful tool call.\n\n## Requirements\n\n- Node.js **22.19.0 or later**\n- A Pirsch OAuth API client with read access. Do not use a write-only access key.\n\n## Configure\n\n```json\n{\n  \"mcpServers\": {\n    \"pirsch\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@verygoodplugins/mcp-pirsch@latest\"],\n      \"env\": {\n        \"PIRSCH_CLIENT_ID\": \"your-read-only-oauth-client-id\",\n        \"PIRSCH_CLIENT_SECRET\": \"your-oauth-client-secret\",\n        \"PIRSCH_DEFAULT_DOMAIN_ID\": \"optional-default-domain-id\"\n      }\n    }\n  }\n}\n```\n\n`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.\n\nOptional `PIRSCH_TIMEZONE` supplies the default timezone for requests that do not explicitly include `timezone`.\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `pirsch_list_domains` | Lists only `id`, hostname, display name, and timezone. |\n| `pirsch_query_statistics` | Reads one documented v1 metric, with dates and filters. |\n| `pirsch_list_filter_options` | Lists allowed values for a documented filter dimension. |\n| `pirsch_compare_periods` | Compares actual totals and visitor series for two periods. |\n\nAll 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.\n\n### Querying statistics\n\n`pirsch_query_statistics` accepts a `metric`, optional `domainId`, and flat camel-case filters. Most metrics require ISO dates:\n\n```json\n{\n  \"metric\": \"pages\",\n  \"domainId\": \"your-domain-id\",\n  \"from\": \"2026-08-01\",\n  \"to\": \"2026-08-23\",\n  \"limit\": 20,\n  \"sort\": \"visitors\",\n  \"direction\": \"desc\"\n}\n```\n\nThe 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.\n\nMetrics 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`.\n\n### Comparing periods\n\nProvide a named `period` (`today`, `yesterday`, `week`, `lastWeek`, `month`, or `lastMonth`) or both explicit date pairs:\n\n```json\n{\n  \"domainId\": \"your-domain-id\",\n  \"from\": \"2026-08-01\",\n  \"to\": \"2026-08-07\",\n  \"compareFrom\": \"2026-07-25\",\n  \"compareTo\": \"2026-07-31\",\n  \"scale\": \"day\"\n}\n```\n\nThe response compares `/statistics/total` and retains the two `/statistics/visitor` series; it does not estimate totals by summing charts.\n\n## 1.0 migration\n\nVersion 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.\n\n| Previous tools | Replacement |\n| --- | --- |\n| `pirsch_overview`, `pirsch_total`, `pirsch_pages`, `pirsch_events`, and other statistic tools | `pirsch_query_statistics` with `metric` |\n| `pirsch_utm` | `pirsch_query_statistics` with one of the `utm_*` metrics |\n| `pirsch_compare` | `pirsch_compare_periods` |\n| Domain discovery | `pirsch_list_domains` |\n\nInput names are now camel-case and flat (`domainId`, `compareFrom`, `eventMetaKey`), not `domain_id`, nested `filter`, or compatibility aliases.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm run lint\nnpm test\nnpm run build\nnpx -y @modelcontextprotocol/inspector@latest --cli node dist/index.js --method tools/list --format json\n```\n\nThe 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.\n\n## Support\n\nFor bugs and feature requests, open an issue in this repository. Pirsch questions are best answered through the [Pirsch documentation](https://docs.pirsch.io/api-sdks/api-v1); package support is maintained by [Very Good Plugins](https://verygoodplugins.com/?utm_source=github).\n\nBuilt with 🧡 by Very Good Plugins.\n",
  "bytes": 4670,
  "sha": "89e67d0e2fa5f3ee6a17afa99c30e9d0d2ae7c740e75b6e9ae6e16c471ba709c",
  "repo_slug": "verygoodplugins/mcp-pirsch",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_verygoodplugins_mcp_pirsch_88da827e/readme"
}