Plausible Analytics MCP

Name: Plausible Analytics MCP
Author: surendranb

Local

github.com/surendranbOther0Updated 1d ago

Repository

About Plausible Analytics MCP

Plausible Analytics MCP gives AI coding agents and LLM harnesses access to Plausible website statistics, on Cloud or self-hosted instances. It includes aggregates, segment breakdowns, real-time visitors, and time series.

Key features

01Visitor and engagement aggregates
02Breakdowns by pages and traffic attributes
03Real-time visitor count
04Daily or monthly time series
05API connectivity and token checks

Use cases

01Review visitor and pageview totals
02Compare traffic across pages or countries
03Check the current active visitor count
04Prepare trend data for charts

MCP support

The MCP server exposes Plausible analytics operations to MCP clients, including aggregate statistics, breakdowns, real-time visitors, and time series.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "surendranb-plausible": {
      "command": "uvx",
      "args": [
        "plausible-mcp"
      ],
      "env": {
        "PLAUSIBLE_API_KEY": "<PLAUSIBLE_API_KEY>",
        "PLAUSIBLE_SITE_ID": "<PLAUSIBLE_SITE_ID>",
        "PLAUSIBLE_BASE_URL": "<PLAUSIBLE_BASE_URL>"
      }
    }
  }
}

Run commanduvx plausible-mcp

Environment variables to set

PLAUSIBLE_API_KEYSecretPlausible Analytics API token

PLAUSIBLE_SITE_IDDefault Plausible site domain / ID (e.g. yourdomain.com)

PLAUSIBLE_BASE_URLCustom self-hosted Plausible instance URL (default: https://plausible.io)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

pypiplausible-mcp0.1.3stdio

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

plausible-mcp

Fast, privacy-first Plausible Analytics Model Context Protocol (MCP) server for AI coding agents and LLM harnesses. Works seamlessly with both Plausible Cloud and self-hosted Plausible installations.

Quick Start

Run with uvx (Python)

export PLAUSIBLE_API_KEY="your_api_key_here"
uvx plausible-mcp

Run with npx (Node / npm bridge)

export PLAUSIBLE_API_KEY="your_api_key_here"
npx -y plausible-analytics-mcp

Environment Configuration

Variable	Description	Default
`PLAUSIBLE_API_KEY`	Your Plausible Stats/Sites API token	Required (or pass via tool `token` arg)
`PLAUSIBLE_BASE_URL`	Base URL for self-hosted Plausible	`https://plausible.io`
`DO_NOT_TRACK`	Set to `1` to disable anonymous telemetry	`0`

Getting an API Key

Log in to Plausible (Cloud or your self-hosted instance).
Go to Settings (user profile menu) -> API Keys.
Click + New Key, name it mcp-agent, and copy the token.
Export as PLAUSIBLE_API_KEY="your_token".

Available Tools

Tool	Description
`get_aggregate_stats(site_id, date_range="30d", metrics=None, token=None)`	High-level visitor, pageview, bounce rate, and session duration totals
`get_breakdown(site_id, property_name="event:page", date_range="30d", limit=20, token=None)`	Segment metrics by pages, traffic sources, countries, browsers, OS, devices
`get_realtime_visitors(site_id, token=None)`	Current count of active visitors on the site right now
`get_timeseries(site_id, date_range="30d", interval="date", token=None)`	Daily or monthly trendline data points for chart generation
`doctor(token=None)`	Test Plausible API connectivity and validate the configured API token
`skills_list()`	List dynamic analytics playbooks and methodology guides
`skill_read(name)`	Fetch full markdown playbook by name (e.g. `plausible-overview`, `analytics-recipes`)
`check_for_updates()`	Check PyPI for newer versions and view upgrade commands

Error Absorption Standard

Errors returned to agents are explicitly classified:

[INPUT_FIXABLE]: Parameter errors (e.g., misspelled site_id, unknown dimension). Fix arguments and retry.
[ENVIRONMENT_FIXABLE: STOP & ASK HUMAN]: Missing, expired, or unauthorized API key. Prompt user with guided setup steps.
[TRANSIENT]: Upstream rate limits (HTTP 429) or network hiccups. Wait briefly and retry.

MCP Client Setup

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "plausible": {
      "command": "uvx",
      "args": ["plausible-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

Or using the npm bridge:

{
  "mcpServers": {
    "plausible": {
      "command": "npx",
      "args": ["-y", "plausible-analytics-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

License

MIT License. See LICENSE for details.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.