{"id":40639795,"url":"https://github.com/verygoodplugins/mcp-pirsch","last_synced_at":"2026-01-21T08:01:57.632Z","repository":{"id":330379916,"uuid":"1049117322","full_name":"verygoodplugins/mcp-pirsch","owner":"verygoodplugins","description":"A Model Context Protocol (MCP) server for Pirsch Analytics, enabling natural language analytics queries, period comparisons, and trend analysis for your website traffic.","archived":false,"fork":false,"pushed_at":"2025-12-25T03:12:11.000Z","size":61,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T16:59:33.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verygoodplugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T14:07:07.000Z","updated_at":"2025-12-25T03:11:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/verygoodplugins/mcp-pirsch","commit_stats":null,"previous_names":["verygoodplugins/mcp-pirsch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/verygoodplugins/mcp-pirsch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-pirsch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-pirsch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-pirsch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-pirsch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verygoodplugins","download_url":"https://codeload.github.com/verygoodplugins/mcp-pirsch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-pirsch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28629922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T08:01:55.197Z","updated_at":"2026-01-21T08:01:57.624Z","avatar_url":"https://github.com/verygoodplugins.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Pirsch Server\n\n[![Version](https://img.shields.io/npm/v/@verygoodplugins/mcp-pirsch)](https://www.npmjs.com/package/@verygoodplugins/mcp-pirsch)\n[![License](https://img.shields.io/npm/l/@verygoodplugins/mcp-pirsch)](LICENSE)\n\nA Model Context Protocol (MCP) server for Pirsch Analytics, enabling natural language analytics queries, period comparisons, and trend analysis for your website traffic.\n\n## Features\n\n- 🔐 **Smart Authentication** - OAuth client credentials with automatic token caching and refresh\n- 📊 **Core Analytics** - Comprehensive stats including visitors, page views, bounce rates, and conversion rates\n- 📈 **Time Series Data** - Flexible visitor trends with day/week/month/year granularity\n- 🔄 **Period Comparisons** - Compare metrics across different time periods with calculated deltas\n- ⚡ **Real-time Insights** - Active visitor tracking with configurable time windows\n- 🎯 **Advanced Filtering** - Full support for Pirsch query parameters including UTM, referrers, and dimensions\n- 🌍 **Multi-domain Support** - Manage analytics across multiple websites from one interface\n\n## Quick Start\n\n### Installation Methods\n\n#### Option 1: Using NPX (No Installation Required)\n\nThe simplest way - no need to install anything globally:\n\n```bash\n# For Claude Desktop\nnpx @verygoodplugins/mcp-pirsch\n\n# For Claude Code\nclaude mcp add pirsch \"npx @verygoodplugins/mcp-pirsch\"\n```\n\n#### Option 2: Global Installation\n\nInstall once, use anywhere:\n\n```bash\n# Install globally\nnpm install -g @verygoodplugins/mcp-pirsch\n\n# For Claude Code\nclaude mcp add pirsch \"mcp-pirsch\"\n```\n\n#### Option 3: Local Development\n\nFor contributing or customization:\n\n```bash\n# Clone and install\ngit clone https://github.com/verygoodplugins/mcp-pirsch.git\ncd mcp-pirsch\nnpm install\nnpm run build\n```\n\n## Configuration\n\n### 1. Get Pirsch API Credentials\n\n1. Log into your [Pirsch Analytics Dashboard](https://pirsch.io)\n2. Navigate to Settings → API Clients\n3. Create a new client with appropriate permissions\n4. Copy your Client ID and Client Secret\n\n### 2. Configure Your Client\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop Configuration\u003c/b\u003e\u003c/summary\u003e\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pirsch\": {\n      \"command\": \"npx\",\n      \"args\": [\"@verygoodplugins/mcp-pirsch\"],\n      \"env\": {\n        \"PIRSCH_CLIENT_ID\": \"your_client_id\",\n        \"PIRSCH_CLIENT_SECRET\": \"your_client_secret\",\n        \"PIRSCH_DEFAULT_DOMAIN_ID\": \"your_domain_id\",\n        \"PIRSCH_TIMEZONE\": \"America/New_York\"\n      }\n    }\n  }\n}\n```\n\n**Or** if installed globally:\n```json\n{\n  \"mcpServers\": {\n    \"pirsch\": {\n      \"command\": \"mcp-pirsch\",\n      \"env\": {\n        \"PIRSCH_CLIENT_ID\": \"your_client_id\",\n        \"PIRSCH_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code Configuration\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add pirsch \"npx @verygoodplugins/mcp-pirsch\" \\\n  --env PIRSCH_CLIENT_ID=your_client_id \\\n  --env PIRSCH_CLIENT_SECRET=your_client_secret \\\n  --env PIRSCH_DEFAULT_DOMAIN_ID=your_domain_id\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor IDE Configuration\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `.mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"pirsch\": {\n      \"command\": \"node\",\n      \"args\": [\"./node_modules/@verygoodplugins/mcp-pirsch/dist/index.js\"],\n      \"env\": {\n        \"PIRSCH_CLIENT_ID\": \"your_client_id\",\n        \"PIRSCH_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### 3. Environment Variables\n\nCreate a `.env` file for local development:\n\n```env\n# Required\nPIRSCH_CLIENT_ID=your_client_id\nPIRSCH_CLIENT_SECRET=your_client_secret\n\n# Optional\nPIRSCH_DEFAULT_DOMAIN_ID=your_domain_id  # Auto-detected if not set\nPIRSCH_TIMEZONE=America/New_York         # Default: UTC\nPIRSCH_TOKEN_SKEW_MS=60000              # Token refresh buffer (default: 60 seconds)\n```\n\n## Available Tools\n\n### Discovery \u0026 Setup\n\n#### `pirsch_list_domains`\nList all accessible domains to discover domain IDs.\n\n**Parameters:**\n- `search` (optional): Filter domains by name\n\n**Example:**\n```\nList all my Pirsch domains\n```\n\n### Core Statistics\n\n#### `pirsch_overview`\nGet cached overview statistics for a domain.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n\n**Returns:** Visitors, page views, and member counts\n\n#### `pirsch_total`\nGet total metrics for a specific period.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Filter object with date range, dimensions, etc.\n\n**Returns:** Total visitors, views, sessions, bounces, bounce rate, conversion rate\n\n#### `pirsch_visitors`\nGet visitor time series data.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Including `scale` (day/week/month/year)\n\n**Example:**\n```\nShow me daily visitor trends for the last month\n```\n\n#### `pirsch_pages`\nGet top pages with performance metrics.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Including:\n  - `sort`: Sort field\n  - `direction`: asc/desc\n  - `search`: Search in page paths\n  - `include_avg_time_on_page`: Include time metrics\n  - `include_title`: Include page titles\n\n#### `pirsch_referrers`\nAnalyze traffic sources and referrers.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Standard filter parameters\n\n#### `pirsch_utm`\nAnalyze UTM campaign parameters.\n\n**Parameters:**\n- `type` (required): source | medium | campaign | content | term\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Standard filter parameters\n\n**Example:**\n```\nShow me UTM source breakdown for this week\n```\n\n#### `pirsch_growth`\nCalculate growth rates across metrics.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `filter` (optional): Date range for growth calculation\n\n### Real-time Analytics\n\n#### `pirsch_active`\nGet currently active visitors and pages.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `start` (optional): Seconds to look back (default: 600)\n\n**Example:**\n```\nShow me active visitors in the last 5 minutes\n```\n\n### Comparative Analytics\n\n#### `pirsch_compare`\nCompare metrics between two time periods.\n\n**Parameters:**\n- `domain_id` (optional): Target domain ID\n- `period` (optional): today | yesterday | week | lastWeek | month | lastMonth\n- `compare` (optional): previous | year | custom\n- `from`, `to` (optional): Custom date range (YYYY-MM-DD)\n- `compare_from`, `compare_to` (optional): Custom comparison range\n- `scale` (optional): day | week | month | year\n\n**Example:**\n```\nCompare this week's traffic to last week\n```\n\n## Filter Parameters\n\nMost tools accept a `filter` object that maps to Pirsch query parameters:\n\n```javascript\n{\n  // Date/Time\n  \"from\": \"2024-01-01\",        // Start date (YYYY-MM-DD)\n  \"to\": \"2024-01-31\",          // End date (YYYY-MM-DD)\n  \"from_time\": \"09:00\",        // Start time (HH:MM)\n  \"to_time\": \"17:00\",          // End time (HH:MM)\n  \"tz\": \"America/New_York\",    // Timezone\n  \n  // Dimensions\n  \"path\": \"/blog/*\",           // Page path pattern\n  \"entry_path\": \"/landing\",    // Entry page\n  \"exit_path\": \"/checkout\",    // Exit page\n  \"pattern\": \"*.pdf\",          // URL pattern\n  \n  // Traffic Sources\n  \"referrer\": \"google.com\",    // Referrer domain\n  \"referrer_name\": \"Google\",   // Referrer name\n  \"channel\": \"organic\",        // Traffic channel\n  \n  // UTM Parameters\n  \"utm_source\": \"newsletter\",\n  \"utm_medium\": \"email\",\n  \"utm_campaign\": \"summer-sale\",\n  \"utm_content\": \"header-cta\",\n  \"utm_term\": \"analytics\",\n  \n  // Device/Browser\n  \"os\": \"Windows\",\n  \"browser\": \"Chrome\",\n  \"platform\": \"desktop\",       // desktop | mobile | unknown\n  \"screen_class\": \"xxl\",\n  \n  // Location\n  \"country\": \"US\",\n  \"city\": \"New York\",\n  \"language\": \"en\",\n  \n  // Pagination/Sorting\n  \"offset\": 0,\n  \"limit\": 100,\n  \"sort\": \"visitors\",\n  \"direction\": \"desc\",         // asc | desc\n  \"search\": \"blog\",\n  \n  // Advanced\n  \"event\": \"signup\",\n  \"event_meta_key\": \"plan\",\n  \"tag\": \"premium\",\n  \"custom_metric_key\": \"revenue\",\n  \"custom_metric_type\": \"float\"\n}\n```\n\n## Usage Examples\n\n### Basic Analytics Query\n```\nShow me the visitor statistics for last week\n```\n\n### Page Performance Analysis\n```\nWhat are my top 10 pages by traffic this month?\n```\n\n### Campaign Tracking\n```\nAnalyze UTM campaign performance for the summer sale\n```\n\n### Traffic Sources\n```\nShow me referrer breakdown excluding direct traffic\n```\n\n### Period Comparison\n```\nCompare this month's metrics to the same period last year\n```\n\n### Real-time Monitoring\n```\nHow many people are on my site right now?\n```\n\n## Development\n\n### Building from Source\n\n```bash\nnpm install\nnpm run build\n```\n\n### Development Mode\n\n```bash\nnpm run dev  # Watch mode with auto-reload\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n#### Invalid credentials error\n- Verify your Client ID and Secret are correct\n- Check that your API client has appropriate permissions in Pirsch\n- Ensure credentials are properly set in environment variables\n\n#### Token refresh failures\n- The server automatically refreshes tokens 60 seconds before expiry\n- Check network connectivity to Pirsch API\n- Verify `PIRSCH_TOKEN_SKEW_MS` is not set too low\n\n### Domain Issues\n\n#### Domain not found\n- Run `pirsch_list_domains` to see available domains\n- Verify `PIRSCH_DEFAULT_DOMAIN_ID` is correct\n- Check API client has access to the domain\n\n#### No data returned\n- Verify the date range contains data\n- Check timezone settings match your Pirsch configuration\n- Ensure proper filtering parameters\n\n### Performance\n\n#### Slow responses\n- Token caching reduces authentication overhead\n- Consider adjusting `PIRSCH_TOKEN_SKEW_MS` for your use case\n- Check network latency to Pirsch API endpoints\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Submit a pull request\n\n## License\n\nMIT - See [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/verygoodplugins/mcp-pirsch/issues)\n- **Documentation**: [Pirsch API Docs](https://docs.pirsch.io/api-sdks/api)\n\n## Credits\n\nBuilt by [Jack Arturo](https://x.com/verygoodplugins) 🧡\n\n- Powered by [Pirsch Analytics](https://pirsch.io)\n- Built with [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol)\n- Part of the [Very Good Plugins](https://verygoodplugins.com?utm_source=github) MCP ecosystem","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-pirsch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverygoodplugins%2Fmcp-pirsch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-pirsch/lists"}