# Pirsch Analytics MCP

> Pirsch Analytics connects your AI client directly to web analytics data. It lets you query site performance—visitor counts, event completions, page views, and traffic sources—using natural language commands instead of opening a dashboard. You can also programmatically manage domains and send real-time tracking hits from within your agent workflow.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** web-analytics, privacy-focused, traffic-monitoring, event-tracking, open-source, visitor-stats

## Description

Yo, peep this: Pirsch Analytics hooks up your AI client straight to web analytics data. You can query site performance—visitor counts, event completions, page views, and traffic sources—using plain English commands instead of having to open some clunky dashboard. Plus, you can programmatically manage domains and send real-time tracking hits right from within your agent's workflow.

### Domain Management

You can keep track of all the sites you're playing with using `list_domains`, which gives you a list of every domain already set up in your Pirsch account. If you need to start monitoring a new site, just run `create_domain` to add it to the system.

### Traffic & Behavior Querying

When it comes to digging into stats, this server lets you pull structured metrics on everything from active users to goal completions for specific time frames. You can get a high-level view of all key website numbers—total visitors, page views, etc.—using `get_statistics_overview` for any domain and date range. Need more detail? Use `get_statistics_page` to pull stats on specific pages, including their traffic volume and view counts. For active users, `get_statistics_active` shows you how many people are currently hitting the site. To track conversions, `get_statistics_goals` pulls statistics specifically related to your defined conversion goals. You can also see where your visitors came from by running `get_statistics_referrer`, which gives detailed data on the referring site (like google.com/search). If you need to track marketing campaigns, `get_statistics_utm_source` gathers metrics based on UTM parameters so you know exactly what worked. Over time, you can analyze historical visitor counts using `get_statistics_visitor`.

### Data Ingestion: Sending Web Activity Data

This is how you feed data back into the system in real-time. You track a single page view (a 'hit') by calling `send_hit`, which sends as much info as possible to keep your analytics accurate. If you're logging multiple user actions, you don't want to spam the API; use `send_event_batch` or `send_hit_batch` to submit several events or hits in one efficient call. You can also send a single, specific user event—like a button click—using `send_event`. It’s all about making sure your agent logs every move.

Basically, you tell your AI client what data you need—say, 'Show me the total visitors for my e-commerce site last quarter,' or 'Log this purchase event now.' The agent picks and runs the right tool call and spits back structured metrics immediately. You're not stuck staring at a dashboard; your agent handles it all.

## Tools

### create_domain
Adds a new website domain to the Pirsch analytics system.

### list_domains
Returns a list of every domain currently configured in your Pirsch account.

### send_event_batch
Submits multiple user events in one call for efficient bulk tracking.

### send_event
Sends a single, specific user event (like 'button_click') to be tracked by Pirsch.

### send_hit_batch
Submits multiple page views (hits) in one call to log several site visits efficiently.

### send_hit
Tracks a single page view (a 'hit') and sends as much information as possible for accurate analytics.

### get_statistics_active
Retrieves statistics showing the count of currently active visitors on a domain.

### get_statistics_events
Gets a list of all tracked user events and their respective counts.

### get_statistics_goals
Pulls statistics specifically related to defined conversion goals on the site.

### get_statistics_overview
Retrieves a high-level summary of all key website metrics for a specified domain and date range.

### get_statistics_page
Gets detailed statistics about specific pages, including view counts and traffic volume.

### get_statistics_referrer
Analyzes where the user came from by listing detailed referrer data (e.g., google.com/search).

### get_statistics_utm_source
Gathers metrics detailing traffic sources based on UTM parameters for campaign tracking.

### get_statistics_visitor
Retrieves historical data and counts for unique visitors to the domain over time.

## Prompt Examples

**Prompt:** 
```
Get visitor statistics for domain ID 'abc-123' from 2023-10-01 to 2023-10-31.
```

**Response:** 
```
I've retrieved the visitor data for domain 'abc-123'. During October, you had 1,250 unique visitors with an average session duration of 2 minutes and 15 seconds.
```

**Prompt:** 
```
Track a page view for 'https://example.com/pricing' from IP 1.2.3.4.
```

**Response:** 
```
The hit for the pricing page has been successfully sent to Pirsch using the `send_hit` action. It is now being processed in your analytics dashboard.
```

**Prompt:** 
```
List all my domains configured in Pirsch.
```

**Response:** 
```
Fetching your domains... I found 3 domains: 'example.com' (ID: abc-123), 'blog.example.com' (ID: def-456), and 'shop.example.com' (ID: ghi-789).
```

## Capabilities

### Domain Management
List all connected domains or create a new one directly through an API call.

### Traffic & Behavior Querying
Retrieve structured statistics on site visits, active users, page performance, and goal completions for specific time periods.

### Data Ingestion (Sending Data)
Stream web activity data by sending single hits (`send_hit`) or batches of events/hits to log user actions in real-time.

## Use Cases

### Auditing Site Health Post-Deployment
A developer needs to validate that all new tracking is working. They first run `list_domains` to get the target ID, then use `send_hit` with a test URL and IP address. Finally, they call `get_statistics_page` to confirm the hit was registered correctly.

### Analyzing Campaign Attribution
A marketing analyst runs a campaign from LinkedIn. They ask their agent: 'Show me the visitor stats for domain X using only UTM sources that match LinkedIn.' The agent uses `get_statistics_utm_source` to isolate the specific performance data.

### Monitoring Conversion Funnels
A product manager wants to track if users complete a complex sign-up sequence. They use `send_event_batch` to log 'step1_complete', then 'step2_submit'. Later, they call `get_statistics_goals` to see the conversion rate.

### Quarterly Performance Review
A data analyst needs a raw report on all site activity for Q3. They use `get_statistics_overview`, specifying the start and end dates, which gathers visitor counts, page views, and goal metrics in one structured call.

## Benefits

- Get immediate insights on visitor patterns. Instead of clicking through multiple tabs to check stats, use `get_statistics_overview` to pull total counts, unique visitors (`get_statistics_visitor`), and page views in a single query.
- Track user actions programmatically. Send hits or events using tools like `send_hit` or `send_event_batch`. This lets your agent simulate traffic flow for testing or record complex interactions without manual intervention.
- Pinpoint campaign success immediately. When you need to know if a marketing push worked, call `get_statistics_utm_source`. It pulls detailed source data so you don't have to dig through spreadsheet columns.
- Manage your analytics stack from the chat. Need to check or add a domain? Use `list_domains` or `create_domain` to keep your infrastructure management right where your code is running, eliminating context switching.
- Understand traffic flow deeply. Don't just know *that* people came; use `get_statistics_referrer` and `get_statistics_page` together to see exactly which source drove the user to a specific page.

## How It Works

The bottom line is that your AI client executes these analytics tools as if they were functions in Python, giving you real-time data access without needing to open any web dashboard.

1. Subscribe to the server and provide your Pirsch Access Token (Client Secret) to the agent.
2. Tell your AI client the exact data point you need. Example: 'What were the visitor counts for domain ABC in November?'
3. The agent calls the appropriate tool (`get_statistics_visitor`, etc.) using structured arguments, and you get a clean JSON response with the requested metrics.

## Frequently Asked Questions

**How do I check my current traffic stats using get_statistics_overview?**
You provide a domain ID and specify the date range. The tool returns one comprehensive view containing key metrics like total hits, active visitors, and page views all in one response.

**What's the difference between send_hit and send_event?**
A `send_hit` tracks a basic page load (a visit). A `send_event` tracks a specific user action, like clicking 'Submit' or viewing a video. You use both to build a full picture.

**Can I list domains before sending data?**
Yes. Use the `list_domains` tool first. This confirms all available domain IDs are correctly registered with Pirsch before you try to send any tracking hits or events.

**How do I get campaign source details using get_statistics_utm_source?**
Just ask for the UTM source statistics, providing the relevant date range. This function pulls detailed data showing exactly which marketing channel (e.g., Facebook, Google) drove the traffic.

**What should I do if my API token expires when I run `list_domains`?**
The agent will receive a 401 Unauthorized error. You need to refresh your Pirsch Access Token via the main dashboard and update the client secret in Vinkius before retrying the query.

**Is using `send_event_batch` better than calling `send_event` multiple times?**
Yes, always use batch actions for efficiency. Sending a large group of events through `send_event_batch` minimizes API calls and drastically improves the speed at which your data gets processed.

**Do I have to call `create_domain` before I can get any statistics?**
Yep, you must run `create_domain` first. The server needs to know about the domain ID before it can fetch anything using tools like `get_statistics_overview` or `get_statistics_page`.

**How does `get_statistics_goals` differ from simply checking visitor stats?**
Goals track specific, defined conversions—like sign-ups or purchases. While visitor data tells you *who* came, the goals tool confirms if they actually completed a critical action.

**How can I get a quick summary of my website's performance for a specific period?**
You can use the `get_statistics_overview` tool. Just provide the Domain ID and the start/end dates (YYYY-MM-DD). The agent will return key metrics like visitors, views, and bounce rate.

**Is it possible to track custom user actions like button clicks?**
Yes! Use the `send_event` tool. You'll need to provide the event name, the current URL, and visitor details (IP and User-Agent) to record the interaction in Pirsch.

**Can I see which pages are the most popular on my site?**
Absolutely. Use the `get_statistics_page` tool with your Domain ID and date range. It will list the top pages along with their respective view counts and visitor data.