Plausible Analytics MCP Server

A stdio-based Model Context Protocol (MCP) server that gives Large Language Models (LLMs) tools to read analytics data from a Plausible Analytics account (cloud-hosted or self-hosted). It operates as a read-only proxy — it does not store, transform, cache, or mutate anything. Every tool call maps to exactly one Plausible API request.

Prerequisites

Python: 3.12 or higher
Package Manager: uv
Plausible Account: Plausible Cloud or self-hosted instance with an API key (Personal Access Token)

Setup Instructions

Clone the repository and navigate into the directory:
```
git clone <repository-url>
cd plausible-mcp
```
Install dependencies using uv:
```
uv sync
```
Create and configure your environment file:
```
cp .env.example .env
```
Edit .env to set your credentials:
```
PLAUSIBLE_API_KEY=your_secret_api_key_here
PLAUSIBLE_BASE_URL=https://plausible.io
```
(For self-hosted instances, replace https://plausible.io with your custom instance URL).

Running the Server

Start the server locally over stdio transport:

uv run python -m src.server

MCP Client Configuration (Claude Desktop)

To connect this MCP server to Claude Desktop, add the following entry to your claude_desktop_config.json file (typically located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "plausible-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/plausible-mcp",
        "run",
        "python",
        "-m",
        "src.server"
      ],
      "env": {
        "PLAUSIBLE_API_KEY": "your_secret_api_key_here",
        "PLAUSIBLE_BASE_URL": "https://plausible.io"
      }
    }
  }
}

Tool Reference

1. `list_sites`

Description: Returns the list of sites/domains accessible by the configured Plausible API key.
Parameters: None
Example Call:
```
list_sites()
```

2. `query_stats`

Description: General-purpose analytics query endpoint wrapping Plausible Stats API v2 (POST /api/v2/query).
Parameters:
- site_id (str, required): The domain name configured in Plausible (min length 1).
- metrics (list[Metric], required): List of confirmed metrics (e.g. visitors, visits, pageviews, bounce_rate, visit_duration, events, scroll_depth, percentage, conversion_rate, group_conversion_rate, average_revenue, total_revenue, time_on_page).
- date_range (DateRangePreset | DateRangeCustom, required): Either a preset string (day, 24h, 7d, 28d, 30d, 91d, month, 6mo, 12mo, year, all) or a 2-element list of ISO8601 date/datetime strings (e.g., ["2026-01-01", "2026-01-07"]).
- dimensions (list[str], optional): List of event, visit, or time dimensions (e.g., visit:source, event:page, time:day).
- filters (list[FilterClause], optional): Structurally validated filter clauses (e.g., [["is", "visit:country", ["US"]]]).
- order_by (list[tuple[str, "asc" | "desc"]], optional): Sorting specifications.
- pagination (Pagination, optional): Limits and offsets ({"limit": 10000, "offset": 0}).

Example Call:

query_stats(
    site_id="example.com",
    metrics=["visitors", "pageviews"],
    date_range="7d",
    dimensions=["visit:source"],
    order_by=[("visitors", "desc")]
)

3. `get_realtime_visitors`

Description: Convenience wrapper querying the current active visitor count over a server-fixed 5-minute window (now - 5 minutes to now).
Parameters:
- site_id (str, required): The domain name configured in Plausible.

Example Call:

get_realtime_visitors(site_id="example.com")

Known Limitations

Filter DSL Structural Validation Only: Filter clauses undergo structural validation (checking element length and operator string), but semantic validation of Plausible's full filter DSL is delegated to the Plausible API itself.
stdio Transport Only: Only stdio transport is supported in this release.
Single Account / Single API Key: Designed for single-tenant operations per server instance.
Read-Only Scope: Purely read-only proxy. Endpoint calls to record pageviews, provision sites, or mutate goals are strictly out of scope.

License

Not yet decided.

Plausible Analytics MCP Server