Skip to main content
Glama
Pirsch MCP Server

Pirsch MCP Server

by charpeni

Pirsch MCP Server

A read-only Model Context Protocol server for the Pirsch Analytics API v1, written in TypeScript.

The server uses the official pirsch-sdk and exposes no tracking or configuration writes.

Installation

Requirements: Node.js 22.19 or later and a Pirsch OAuth client with read scopes.

Most MCP clients can run the package on demand without a global installation. Add the following server configuration, replacing the credential placeholders:

{
  "mcpServers": {
    "pirsch": {
      "command": "npx",
      "args": ["-y", "@charpeni/pirsch-mcp"],
      "env": {
        "PIRSCH_CLIENT_ID": "your-client-id",
        "PIRSCH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Alternatively, install the executable globally:

npm install --global @charpeni/pirsch-mcp

Then configure your MCP client to run pirsch-mcp.

Create an OAuth client from the Pirsch dashboard's Integration Settings or Account Settings. Disable write operations to keep its scopes read-only. Pirsch access keys beginning with pa_ are write-only and cannot read statistics.

Related MCP server: umami-mcp-server

Tools

pirsch_list_domains

Lists every domain available to the configured OAuth client. Each result contains only the fields needed to select a statistics target: id, hostname, and optional displayName and timezone values.

Account-scoped OAuth clients can use this tool to discover all accessible domains. Agents can switch domains by passing the selected id as domainId to pirsch_query_statistics.

pirsch_get_domain

Returns the Pirsch SDK's default domain. Dashboard-scoped clients return their dashboard domain. Account-scoped clients can access multiple domains, so use the Pirsch dashboard to select the intended PIRSCH_DOMAIN_ID.

pirsch_query_statistics

Queries traffic, pages, events, acquisition, device, geography, tag, keyword, and funnel statistics.

Available metrics:

total, visitors, pages, entry_pages, exit_pages, session_duration,
time_on_page, conversion_goals, events, event_metadata, event_list,
event_pages, growth, active_visitors, time_of_day, languages, referrers,
operating_systems, operating_system_versions, browsers, browser_versions,
countries, regions, cities, platforms, screen_classes, utm_sources,
utm_mediums, utm_campaigns, utm_contents, utm_terms, tag_keys, tags,
keywords, funnels

Example:

{
  "metric": "pages",
  "from": "2026-07-01",
  "to": "2026-07-31",
  "limit": 10,
  "sort": "visitors",
  "direction": "desc"
}

The domainId argument can be omitted when PIRSCH_DOMAIN_ID is configured. The server never automatically selects a domain for statistics queries because account-scoped clients can access multiple domains.

A typical multi-domain flow is:

  1. Call pirsch_list_domains.

  2. Match the requested hostname or display name.

  3. Pass that domain's id to pirsch_query_statistics.

Configuration

Environment variable

Required

Default

Description

PIRSCH_CLIENT_ID

Yes

Pirsch OAuth client ID

PIRSCH_CLIENT_SECRET

Yes

Pirsch OAuth client secret

PIRSCH_DOMAIN_ID

No

Default domain ID; otherwise pass domainId

PIRSCH_HOSTNAME

No

localhost

Hostname passed to the SDK; unused by reads

PIRSCH_BASE_URL

No

https://api.pirsch.io

Pirsch API base URL

PIRSCH_TIMEOUT_MS

No

5000

Positive request timeout in milliseconds

Credentials are loaded lazily. MCP clients can start the server and list its tools without credentials, but tool calls require them.

MCP Inspector

Set the required credentials in your shell:

export PIRSCH_CLIENT_ID="your-client-id"
export PIRSCH_CLIENT_SECRET="your-client-secret"

Inspect the published package:

npx -y @modelcontextprotocol/inspector \
  -e "PIRSCH_CLIENT_ID=$PIRSCH_CLIENT_ID" \
  -e "PIRSCH_CLIENT_SECRET=$PIRSCH_CLIENT_SECRET" \
  npx -y @charpeni/pirsch-mcp

Inspector does not forward arbitrary shell variables to spawned stdio servers, so the credentials are passed explicitly with -e.

Development

Install dependencies and run the complete quality gate:

pnpm install
pnpm check

List the local server's tools through Inspector without Pirsch credentials:

pnpm inspect:list

Run the local Inspector web UI after exporting the credentials:

pnpm inspect

Other development commands:

pnpm dev
pnpm build
pnpm format
pnpm lint
pnpm typecheck
pnpm test

Available Tools

3 tools
pirsch_get_domainA

Return the Pirsch SDK's default domain. Dashboard-scoped clients return their dashboard domain. Account-scoped clients may have additional domains and should select one explicitly for statistics queries.

Inputs: no named parameters.

pirsch_list_domainsA

List every Pirsch domain available to the configured OAuth client. Returns safe domain summaries for selecting domainId in statistics queries.

Inputs: no named parameters.

pirsch_query_statisticsA

Read Pirsch Analytics v1 statistics for a domain and date range. Pass domainId from pirsch_list_domains to query a specific domain. Supports traffic, pages, events, acquisition, devices, geography, tags, keywords, and funnels.

Inputs: to (required), from (required), metric (required), tag, +35 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: get_domain returns the default, list_domains enumerates available domains, and query_statistics fetches analytics. No overlap or ambiguity exists.

    Naming Consistency5/5

    All tool names follow a consistent pattern of 'pirsch_' prefix plus a verb_noun structure (get, list, query). This makes the API predictable and easy to understand.

    Tool Count5/5

    Three tools is well-scoped for an analytics server: domain discovery, default selection, and statistics querying. Each tool is necessary and there is no bloat.

    Completeness5/5

    The tool surface fully covers the workflow of selecting a domain and querying comprehensive statistics (traffic, pages, events, etc.). No obvious missing operations or dead ends exist for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      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
      Not graded
      quality
      D
      maintenance
      MCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.
      12 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for Umami analytics, enabling natural language queries of website stats, traffic trends, events, sessions, and analytics reports.
      13
      10 npm
      1
      Elastic 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables natural language analytics queries for Pirsch Analytics, providing comprehensive website traffic statistics, period comparisons, and trend analysis through an MCP interface.
      4
      54 npm
      1
      MIT