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.

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