# Piwik PRO MCP

> Piwik PRO connects your AI agent directly to an analytics suite for privacy-compliant web tracking. List every app, check user access levels, and run complex custom queries using JSON to extract specific conversion metrics without leaving your IDE.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** web-analytics, privacy-compliant, gdpr, data-visualization, custom-queries, user-behavior

## Description

You connect this server to your AI agent, and you get full control over the analytics data from Piwik PRO. You can audit tracking sites and run deep-dive reports conversationally, keeping everything privacy-compliant right where you are.

**Audit Site Presence: Checking Your Footprint**

Need to know every website or application container tracked in your account? Use `list_piwik_apps` to pull a full list of all the apps Piwik PRO tracks. If you just want to see what sites are set up for tracking, run `list_piwik_sites`. These two tools let you verify that your entire digital footprint is accounted for before you start querying anything.

**View Organizational Structure: Who's Doing What Where**

You can pull an overview of the whole setup. To see which dashboards are available to everyone, run `list_piwik_dashboards`. For managing permissions or just checking who has access, use `list_piwik_users` to get the current user roster and their roles in the organization's Piwik PRO structure. You can also audit specific conversion goals for a given app by calling `list_piwik_goals`, which helps you make sure your key business funnels are actually being monitored.

**Extract Custom Data Points: Running the Deep Dive**

This is where the real power is. Instead of relying on pre-built reports, you execute custom analytics queries using `query_piwik_analytics`. This tool demands a detailed JSON body; that's how you tell your agent exactly what dimensions and metrics you want to pull out. You don't just get numbers—you get specific, precise data sets based on complex rules you define in the query.

**Putting It Together: The Full Workflow**

When you combine these tools, you can build a complete audit trail right inside your IDE. First, you might start by listing all available sites with `list_piwik_sites` to confirm the scope of the data. Then, if you need to check permissions, you'll run `list_piwik_users`. If everything looks right, and you know which apps are live, you use `list_piwik_apps` for a full breakdown of containers.

To focus on revenue or conversions, you call `list_piwik_goals` to confirm the key funnels. Once you've confirmed the scope—the sites, the apps, and the goals—you wrap it all up by executing the query with `query_piwik_analytics`. By providing a precise JSON payload, your agent pulls exactly the dimensions and metrics you need, giving you granular data without ever having to leave your terminal. It keeps the process clean and focused on the numbers that matter.

## Tools

### list_piwik_apps
Gets a list of all websites and apps tracked in the Piwik PRO account.

### list_piwik_dashboards
Retrieves a listing of available dashboards within your Piwik PRO instance.

### list_piwik_goals
Lists conversion goals that are defined for a specific application.

### list_piwik_sites
Provides a list of all tracking sites configured in your Piwik PRO account.

### list_piwik_users
Retrieves the current user roster and their roles within the organization's Piwik PRO setup.

### query_piwik_analytics
Executes a custom analytics query by accepting a detailed JSON body for precise data extraction.

## Prompt Examples

**Prompt:** 
```
List all websites tracked in my Piwik PRO account.
```

**Response:** 
```
I've retrieved your apps. You have 3 tracked sites: 'Main Corporate Site', 'E-commerce Portal', and 'Customer Help Center'. Would you like to see the conversion goals for any of these?
```

**Prompt:** 
```
What are the conversion goals defined for the 'E-commerce Portal' (ID: 12345)?
```

**Response:** 
```
There are 4 goals defined for this portal: 'Completed Purchase', 'Added to Cart', 'Newsletter Signup', and 'Contact Form Submission'.
```

**Prompt:** 
```
List all users with access to our Piwik PRO organization.
```

**Response:** 
```
I've retrieved the user list. There are 8 users with various roles, including 2 Administrators, 4 Editors, and 2 Viewers.
```

## Capabilities

### Audit Site Presence
List every website or application container tracked within your Piwik PRO account.

### Extract Custom Data Points
Run a specific analytics query by providing a JSON body, allowing you to pull precise dimensions and metrics.

### Track Conversion Goals
List all defined conversion goals for a selected application, helping audit key business funnels.

### View Organizational Structure
Retrieve lists of available dashboards, sites, and account users to maintain an overview of the setup.

## Use Cases

### Checking compliance scope
A Privacy Officer needs to confirm if an old marketing microsite is still being tracked. They run `list_piwik_sites`. The agent returns the list, allowing the officer to verify the domain and immediately check user access using `list_piwik_users` before proceeding.

### Deep-dive funnel analysis
A Marketing Manager suspects a drop-off on the checkout page. Instead of running reports manually, they prompt their agent to execute a complex query via `query_piwik_analytics`, specifying dimensions like 'Cart Value' and 'Error Code' in the JSON body.

### Auditing app coverage
A developer needs to know every subdomain that feeds into their main application. They use `list_piwik_apps` first, which returns a list of all containers. This validates that no new services have been deployed without being accounted for in the analytics scope.

### Verifying conversion metrics
A team lead wants to audit if 'Newsletter Signup' is correctly defined for the main portal. They use `list_piwik_goals` against the specific app ID, confirming that all necessary funnels are active and ready for monitoring.

## Benefits

- Get immediate visibility into your entire setup. Use `list_piwik_apps` to see every website container tracked, preventing you from forgetting an important data source.
- Avoid building complex JSON payloads manually. The `query_piwik_analytics` tool lets you pass structured queries directly to extract specific metrics and dimensions instantly.
- Stay compliant and organized. Running `list_piwik_users` allows Privacy Officers to verify who has access, keeping an audit trail of user roles and permissions.
- Track success without leaving your IDE. Use `list_piwik_goals` to list conversion objectives for a specific app right where you're working on the code or analysis.
- See the big picture quickly. Running `list_piwik_dashboards` gives you a fast overview of available analytical views, helping guide stakeholders to the right data set.

## How It Works

The bottom line is, you talk to your agent, and the Piwik PRO server does the heavy lifting to get you structured data without you ever leaving the chat window.

1. Subscribe to this server and input your Piwik PRO Client ID, Secret, and Subdomain credentials.
2. Call a specific tool (e.g., `list_piwik_apps`) or pass a JSON body to `query_piwik_analytics` via your AI client.
3. Your agent receives the requested data—be it a list of users or raw metrics—and presents it directly in conversation.

## Frequently Asked Questions

**How do I check all my tracked apps using list_piwik_apps?**
You call `list_piwik_apps`. This tool pulls and lists every website or application container currently active in your Piwik PRO account. It’s the fastest way to audit your scope.

**Can I check user roles using list_piwik_users?**
Yes, `list_piwik_users` retrieves a full roster of every user with access. You'll get details on their assigned roles (Admin, Editor, Viewer) right in the response.

**What is the difference between list_piwik_sites and list_piwik_apps?**
`list_piwik_sites` lists the physical tracking sites. `list_piwik_apps` lists containers, which are often used to group related apps or websites under a single analytical umbrella.

**Is query_piwik_analytics complex?**
It requires passing a JSON body, so it is technically advanced. But the benefit is that you get deep-dive reporting on specific metrics—like correlating 'page load time' with 'conversion goal X'—that simple listing tools can't provide.

**Do I need to run list_piwik_dashboards before querying?**
No. While `list_piwik_dashboards` shows what reports exist, it doesn't contain the raw data. You still have to use `query_piwik_analytics` to actually extract the numbers you want.

**What credentials do I need when setting up my connection to use `list_piwik_users`?**
You must supply your Piwik PRO Client ID, Client Secret, and Subdomain. These three pieces of information authenticate your AI client, ensuring that only authorized requests access your account data.

**What format should I use when calling the `query_piwik_analytics` tool?**
The function requires a structured JSON body for all parameters. You need to map out the specific dimensions and metrics you want to query in proper JSON syntax before sending the request.

**How does `list_piwik_goals` help me audit conversions for an application?**
It returns a list of all defined conversion goals associated with a specific application ID. This lets you confirm exactly what metrics count as success without writing a full custom query.

**How do I create API credentials in Piwik PRO?**
Log in to Piwik PRO, go to **Menu** > **Administration**. In the sidebar, select **Personal API keys** and click **Create a new key**. You will receive a Client ID and Client Secret.

**What is the subdomain format?**
The subdomain is the host of your Piwik PRO instance, for example `yourcompany.piwik.pro` or `app.piwik.pro`.

**Can I run raw queries against the analytics API?**
Yes! Use the `query_piwik_analytics` tool and provide a valid JSON query body. This allows you to extract precise data points using the Piwik PRO Query API format.