MCP Server

The Piwik PRO MCP Server lets you connect AI assistants, such as Claude, Cursor, or other MCP-compatible clients, directly to your Piwik PRO account. It lets you use natural language to query analytics data, manage tags, and configure tracking without working through the interface manually.

It's based on the open Model Context Protocol (MCP) standard and is available as an open-source project on GitHub.

What can you do with the MCP Server?

• Run flexible queries with custom date ranges and filters
• Discover available dimensions and metrics
• Get answers to analytics questions in seconds

Have a conversation with your analytics data

Ask questions about your visitors, page views, conversions, and more. The Query API lets you explore data using natural language, so you don’t need to build reports manually.

Manage analytics configuration

Keep your analytics setup organized without leaving the conversation with your AI assistant:

• Annotations — Mark important events, campaigns, or deployments
• Goals — Create and manage conversion tracking
• Custom dimensions — Extend your tracking with custom data points

Control Tag Manager

Manage your tracking setup without touching your website code:

• Tags — Create and configure tracking tags
• Triggers — Define when and where tags fire
• Variables — Store and reuse dynamic values
• Version Control — Publish changes when you're ready

Build audiences with Data Activation (DA)

Create targeted audiences based on user behavior and update segmentation rules in real time.

Manage settings

Fine-tune your Piwik PRO setup — manage apps, configure tracker settings, and access container installation code.

Prerequisites

• A Piwik PRO account with API credentials
• uv or Docker
• An MCP-compatible client, such as Claude Desktop, Claude Code, or Cursor

Generate API credentials

Go to the API credentials page in your account:

https://YOUR_ACCOUNT.piwik.pro/profile/api-credentials

Generate new credentials and note the following values:

Installation

All MCP clients use a JSON configuration file to register MCP servers. The file name and location depend on the client:

• Claude Desktop — Go to Settings > Developer > Edit Config to open the folder containing claude_desktop_config.json.
• Cursor — See the Cursor MCP documentation for config file locations.
• Claude Code — See the Claude Code MCP documentation for installation instructions.

Choose one of the options below, paste the configuration into your client's config file, and enter your credentials.

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "uvx",
      "args": ["piwik-pro-mcp"],
      "env": {
        "PIWIK_PRO_HOST": "YOUR_ACCOUNT.piwik.pro",
        "PIWIK_PRO_CLIENT_ID": "YOUR_CLIENT_ID",
        "PIWIK_PRO_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/piwikpro/mcp:latest"],
      "env": {
        "PIWIK_PRO_HOST": "YOUR_ACCOUNT.piwik.pro",
        "PIWIK_PRO_CLIENT_ID": "YOUR_CLIENT_ID",
        "PIWIK_PRO_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

After updating the configuration, restart your MCP client to apply the changes.

First use

The server starts in safe mode by default, so you can explore your data without worrying about accidental changes. Try these prompts to get started:

List my Piwik PRO apps.

Which source had the most conversions?

Show me conversion trends for the past month.

List tags in my "app name" app.

Show the most common sources of LLM/AI traffic from the last quarter.

Which country generated the highest traffic over the past 3 months?

List the top 5 most visited blog posts (pages with /blog/ in the URL) from last month.

Ready to make changes?

Once you're comfortable, disable safe mode to enable create, update, and delete operations. Add this to your environment variables:

PIWIK_PRO_SAFE_MODE=0

Then try prompts like:

Add an annotation for today's marketing campaign launch.
Create a new goal to track signups on the /thank-you page.
In app "app name", add a tag that fires on all page views.

Feedback and contributions

This project is open source, and we welcome your feedback. If you have suggestions, run into issues, or want to request a feature, open an issue on the GitHub repository or contact our support team.