io.github.verygoodplugins/mcp-pirsch

Official

by verygoodplugins · TypeScript

MCP Pirsch

Pirsch Analytics with natural language queries and trend analysis

Query Pirsch Analytics with natural language and analyze website traffic trends.

README.md14 KBView on GitHub

MCP Pirsch Server

A Model Context Protocol (MCP) server for Pirsch Analytics, enabling natural language analytics queries, period comparisons, and trend analysis for your website traffic.

Features

🔐 Smart Authentication - OAuth client credentials with automatic token caching and refresh
📊 Core Analytics - Comprehensive stats including visitors, page views, bounce rates, and conversion rates
📈 Time Series Data - Flexible visitor trends with day/week/month/year granularity
🔄 Period Comparisons - Compare metrics across different time periods with calculated deltas
🎯 Goals & Events - Read conversion goals, event activity, and event-specific page performance
🧭 Session Drilldown - Inspect entry pages, exit pages, session lists, and per-session timelines
⚡ Real-time Insights - Active visitor tracking with configurable time windows
🎯 Advanced Filtering - Full support for Pirsch query parameters including UTM, referrers, and dimensions
🌍 Multi-domain Support - Manage analytics across multiple websites from one interface

Quick Start

Installation Methods

Option 1: Using NPX (No Installation Required)

The simplest way - no need to install anything globally:

bash

# For Claude Desktop
npx @verygoodplugins/mcp-pirsch

# For Claude Code
claude mcp add pirsch "npx @verygoodplugins/mcp-pirsch"

Option 2: Global Installation

Install once, use anywhere:

bash

# Install globally
npm install -g @verygoodplugins/mcp-pirsch

# For Claude Code
claude mcp add pirsch "mcp-pirsch"

Option 3: Local Development

For contributing or customization:

bash

# Clone and install
git clone https://github.com/verygoodplugins/mcp-pirsch.git
cd mcp-pirsch
npm install
npm run build

Configuration

1. Get Pirsch API Credentials

Log into your Pirsch Analytics Dashboard
Navigate to Settings → API Clients
Create a new client with appropriate permissions
Copy your Client ID and Client Secret

2. Configure Your Client

<details> <summary>Claude Desktop Configuration</summary>

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "pirsch": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-pirsch"],
      "env": {
        "PIRSCH_CLIENT_ID": "your_client_id",
        "PIRSCH_CLIENT_SECRET": "your_client_secret",
        "PIRSCH_DEFAULT_DOMAIN_ID": "your_domain_id",
        "PIRSCH_TIMEZONE": "America/New_York"
      }
    }
  }
}

Or if installed globally:

json

{
  "mcpServers": {
    "pirsch": {
      "command": "mcp-pirsch",
      "env": {
        "PIRSCH_CLIENT_ID": "your_client_id",
        "PIRSCH_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

</details> <details> <summary>Claude Code Configuration</summary>

bash

claude mcp add pirsch "npx @verygoodplugins/mcp-pirsch" \
  --env PIRSCH_CLIENT_ID=your_client_id \
  --env PIRSCH_CLIENT_SECRET=your_client_secret \
  --env PIRSCH_DEFAULT_DOMAIN_ID=your_domain_id

</details> <details> <summary>Cursor IDE Configuration</summary>

Add to .mcp.json in your project:

json

{
  "mcpServers": {
    "pirsch": {
      "command": "node",
      "args": ["./node_modules/@verygoodplugins/mcp-pirsch/dist/index.js"],
      "env": {
        "PIRSCH_CLIENT_ID": "your_client_id",
        "PIRSCH_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

</details>

3. Environment Variables

Create a .env file for local development:

env

# Required
PIRSCH_CLIENT_ID=your_client_id
PIRSCH_CLIENT_SECRET=your_client_secret

# Optional
PIRSCH_DEFAULT_DOMAIN_ID=your_domain_id  # Auto-detected if not set
PIRSCH_TIMEZONE=America/New_York         # Default: UTC
PIRSCH_TOKEN_SKEW_MS=60000              # Token refresh buffer (default: 60 seconds)

Available Tools

Discovery & Setup

`pirsch_list_domains`

List all accessible domains to discover domain IDs.

Parameters:

search (optional): Filter domains by name

Example:

code

List all my Pirsch domains

Core Statistics

`pirsch_overview`

Get cached overview statistics for a domain.

Parameters:

domain_id (optional): Target domain ID

Returns: Visitors, page views, and member counts

Note: This is the Pirsch cached overview endpoint. Filters do not apply, and it should not be used as a substitute for pirsch_total over a custom date range.

`pirsch_total`

Get total metrics for a specific period.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Filter object with date range, dimensions, etc.

Most analytics tools accept filter fields either inside filter or as top-level arguments. Both forms are supported for MCP client compatibility.

Returns: Total visitors, views, sessions, bounces, bounce rate, conversion rate, and custom metric aggregates

`pirsch_visitors`

Get visitor time series data.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Including scale (day/week/month/year)

Example:

code

Show me daily visitor trends for the last month

`pirsch_pages`

Get top pages with performance metrics.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Including:
- sort: Sort field
- direction: asc/desc
- search: Search in page paths
- include_avg_time_on_page: Include time metrics
- include_title: Include page titles

Tip: Exact path: "/news/" still matches only that URL. For section queries on page-style tools, path-shaped values such as search: "/news/", path: "~/news/", or pattern: "/news/*" are narrowed again inside the MCP so /documentation/news/... does not leak into /news/... results. path_prefix is also available when you want an explicit root-prefix filter. Top-level search, path, and path_prefix arguments are also accepted.

`pirsch_entry_pages`

Get entry page analytics.

`pirsch_exit_pages`

Get exit page analytics.

`pirsch_referrers`

Analyze traffic sources and referrers.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Standard filter parameters

`pirsch_goals`

Get conversion goals together with their observed stats.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Standard filter parameters

`pirsch_events`

Get aggregated event statistics including counts, visitors, conversion rate, and metadata keys.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Standard filter parameters

`pirsch_event_pages`

Get pages on which a specific event fired.

Parameters:

domain_id (optional): Target domain ID
filter (required): Standard filter parameters, including event

The event can also be passed as a top-level event argument. If your client uses goal payload field names, event_name is accepted as an alias and normalized to event. The same path-prefix narrowing described for pirsch_pages also applies here.

`pirsch_utm`

Analyze UTM campaign parameters.

Parameters:

type (required): source | medium | campaign | content | term
domain_id (optional): Target domain ID
filter (optional): Standard filter parameters

Example:

code

Show me UTM source breakdown for this week

`pirsch_growth`

Calculate growth rates across metrics.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Date range for growth calculation

Real-time Analytics

`pirsch_active`

Get currently active visitors and pages.

Parameters:

domain_id (optional): Target domain ID
start (optional): Seconds to look back (default: 600)

Example:

code

Show me active visitors in the last 5 minutes

Session Analytics

`pirsch_sessions`

Get session list data including entry/exit pages, duration, geography, device, and traffic source context.

Parameters:

domain_id (optional): Target domain ID
filter (optional): Standard filter parameters

`pirsch_session_details`

Get the chronological page-view and event timeline for a single session.

Parameters:

domain_id (optional): Target domain ID
filter (required): Must include both visitor_id and session_id

Comparative Analytics

`pirsch_compare`

Compare metrics between two time periods using true period totals from Pirsch totals, plus the matching visitor series for charts.

Parameters:

domain_id (optional): Target domain ID
period (optional): today | yesterday | week | lastWeek | month | lastMonth
compare (optional): previous | year | custom
from, to (optional): Custom date range (YYYY-MM-DD)
compare_from, compare_to (optional): Custom comparison range
scale (optional): day | week | month | year

Example:

code

Compare this week's traffic to last week

Filter Parameters

Most tools accept a filter object that maps to Pirsch query parameters:

javascript

{
  // Date/Time
  "from": "2024-01-01",        // Start date (YYYY-MM-DD)
  "to": "2024-01-31",          // End date (YYYY-MM-DD)
  "from_time": "09:00",        // Start time (HH:MM)
  "to_time": "17:00",          // End time (HH:MM)
  "tz": "America/New_York",    // Timezone
  
  // Dimensions
  "path": "~/news/",           // Exact or operator-based path filter (~ contains, ! not, ^ does-not-contain)
  "entry_path": "/landing",    // Entry page
  "exit_path": "/checkout",    // Exit page
  "pattern": "*.pdf",          // URL pattern
  
  // Traffic Sources
  "referrer": "google.com",    // Referrer domain
  "referrer_name": "Google",   // Referrer name
  "channel": "organic",        // Traffic channel
  
  // UTM Parameters
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer-sale",
  "utm_content": "header-cta",
  "utm_term": "analytics",
  
  // Device/Browser
  "os": "Windows",
  "browser": "Chrome",
  "platform": "desktop",       // desktop | mobile | unknown
  "screen_class": "xxl",
  
  // Location
  "country": "US",
  "city": "New York",
  "language": "en",
  
  // Pagination/Sorting
  "offset": 0,
  "limit": 100,
  "sort": "visitors",
  "direction": "desc",         // asc | desc
  "search": "/news/",          // Path-shaped searches are narrowed to root-prefix matches on page-style tools
  "path_prefix": "/news/",     // Optional explicit MCP-local prefix matcher for page-style tools
  "keyword": "wordpress crm",  // Google Search Console keyword filter
  
  // Advanced
  "event": "signup",
  "event_meta_key": "plan",
  "tag": "premium",
  "visitor_id": "12345...",    // Required together with session_id for pirsch_session_details
  "session_id": "67890",
  "custom_metric_key": "revenue",
  "custom_metric_type": "float"
}

Usage Examples

Basic Analytics Query

code

Show me the visitor statistics for last week

Page Performance Analysis

code

What are my top 10 /news/ posts by traffic this month?

Campaign Tracking

code

Analyze UTM campaign performance for the summer sale

Traffic Sources

code

Show me referrer breakdown excluding direct traffic

Period Comparison

code

Compare this month's metrics to the same period last year

Real-time Monitoring

code

How many people are on my site right now?

Goals and Events

code

Show me conversion goals and top event-driven pages for the last 90 days

Session Investigation

code

List recent sessions that entered on /news/ and inspect one session in detail

Development

Building from Source

bash

npm install
npm run build

Development Mode

bash

npm run dev  # Watch mode with auto-reload

Testing

bash

npm test

Troubleshooting

Authentication Issues

Invalid credentials error

Verify your Client ID and Secret are correct
Check that your API client has appropriate permissions in Pirsch
Ensure credentials are properly set in environment variables

Token refresh failures

The server automatically refreshes tokens 60 seconds before expiry
Check network connectivity to Pirsch API
Verify PIRSCH_TOKEN_SKEW_MS is not set too low

Domain Issues

Domain not found

Run pirsch_list_domains to see available domains
Verify PIRSCH_DEFAULT_DOMAIN_ID is correct
Check API client has access to the domain

No data returned

Verify the date range contains data
Check timezone settings match your Pirsch configuration
Ensure proper filtering parameters
Use pirsch_total for custom date range totals; pirsch_overview is cached and not filterable
For page-style tools, path-shaped search, ~/path/, and /path/* filters are narrowed to root-prefix matches inside the MCP
Use path_prefix when you want explicit prefix behavior without relying on Pirsch operators

Performance

Slow responses

Token caching reduces authentication overhead
Consider adjusting PIRSCH_TOKEN_SKEW_MS for your use case
Check network latency to Pirsch API endpoints

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

License

MIT - See LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: Pirsch API Docs

Credits

Built by Jack Arturo 🧡

Powered by Pirsch Analytics
Built with Model Context Protocol SDK
Part of the Very Good Plugins MCP ecosystem

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-pirsch": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-pirsch@0.1.1"
      ]
    }
  }
}