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
• ⚡ 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:

claude mcp add pirsch-mcp \
  -e PIRSCH_CLIENT_ID=your_client_id \
  -e PIRSCH_CLIENT_SECRET=your_client_secret \
  -- npx -y @joelwmale/pirsch-mcp

Option 2: Global Installation

Install once, use anywhere:

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

# For Claude Code
claude mcp add pirsch-mcp \
  -e PIRSCH_CLIENT_ID=your_client_id \
  -e PIRSCH_CLIENT_SECRET=your_client_secret \
  -- pirsch-mcp

Option 3: Local Development

For contributing or customization:

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

Configuration

1. Get Pirsch API Credentials

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

2. Configure Your Client

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

{
  "mcpServers": {
    "pirsch-mcp": {
      "command": "npx",
      "args": ["-y", "@joelwmale/pirsch-mcp"],
      "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:

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

Note for nvm users: Claude Desktop may not inherit your shell's PATH. If npx or pirsch-mcp isn't found, use the full path: "/Users/yourname/.nvm/versions/node/vX.X.X/bin/npx" as the command value.

claude mcp add pirsch-mcp \
  -e PIRSCH_CLIENT_ID=your_client_id \
  -e PIRSCH_CLIENT_SECRET=your_client_secret \
  -e PIRSCH_DEFAULT_DOMAIN_ID=your_domain_id \
  -- npx -y @joelwmale/pirsch-mcp

Note: The -- separator is required — it tells the CLI that everything after it is the command to run, not a flag.

Add to .mcp.json in your project:

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

3. Environment Variables

Create a .env file for local development:

# 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:

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

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.

Returns: Total visitors, views, sessions, bounces, bounce rate, conversion rate

pirsch_visitors

Get visitor time series data.

Parameters:

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

Example:

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

pirsch_referrers

Analyze traffic sources and referrers.

Parameters:

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

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:

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:

Show me active visitors in the last 5 minutes

Events & Conversions

pirsch_events

List all custom events tracked on a domain with visitor counts, conversion rates, and available metadata keys.

Parameters:

• domain_id (optional): Target domain ID
• filter (optional): Date range, path, country, etc.

Example:

What events are being tracked on my site this month?

pirsch_goals

Get conversion goal performance for all configured goals.

Parameters:

• domain_id (optional): Target domain ID
• filter (optional): Date range and standard filters

Example:

How are my conversion goals performing this week?

pirsch_funnel

Analyse step-by-step drop-off through a funnel.

Parameters:

• funnel_id (required): Funnel ID from your Pirsch dashboard
• domain_id (optional): Target domain ID
• filter (optional): Date range and standard filters

Returns: Per-step visitor counts, drop-off rates, and relative visitor percentages

Example:

Show me drop-off through funnel abc123 this month

Session Analysis

pirsch_sessions

Get individual session records with full detail.

Parameters:

• domain_id (optional): Target domain ID
• filter (optional): Including offset/limit for pagination (max 100 per request), plus any standard filters

Returns: Entry/exit pages, duration, device info, location, UTM data per session

Example:

Show me recent sessions from mobile users in Australia

Discovery

pirsch_filter_options

Discover available values for a filter dimension within a date range. Useful before filtering to know what values exist.

Parameters:

• dimension (required): referrer/name | hostname | page | event | country | browser | utm/source | tag
• domain_id (optional): Target domain ID
• filter (optional): Date range to scope the options

Example:

What countries have visitor data this month?
What events are available to filter by?

Comparative Analytics

pirsch_compare

Compare metrics between two time periods.

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:

Compare this week's traffic to last week

Filter Parameters

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

{
  // 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": "/blog/*",           // Page path pattern
  "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": "blog",
  
  // Advanced
  "event": "signup",
  "event_meta_key": "plan",
  "tag": "premium",
  "custom_metric_key": "revenue",
  "custom_metric_type": "float"
}

Usage Examples

Basic Analytics Query

Show me the visitor statistics for last week

Page Performance Analysis

What are my top 10 pages by traffic this month?

Campaign Tracking

Analyze UTM campaign performance for the summer sale

Traffic Sources

Show me referrer breakdown excluding direct traffic

Period Comparison

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

Real-time Monitoring

How many people are on my site right now?

Development

Building from Source

npm install
npm run build

Development Mode

npm run dev  # Watch mode with auto-reload

Testing

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

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:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT - See LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Pirsch API Docs

Credits

Maintained by Joel Male.

Originally built by Jack Arturo / Very Good Plugins — full credit to the original author.

• Powered by Pirsch Analytics
• Built with Model Context Protocol SDK