Plausible Analytics MCP

io.github.surendranbPublished by GitHub account surendranbv0.1.3Updated Nov 3, 2026

Plausible Analytics MCP: privacy-first website stats, real-time visitors, breakdowns, and trends.

VerifiedSTDIODesktop onlyWeb Search & Scraping Data & Analytics

Server details

Identifier: io.github.surendranb/plausible-mcp
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Oct 29, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account surendranb for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.surendranb%2Fplausible-mcp.svg)](https://sourceweft.com/mcp/io.github.surendranb%2Fplausible-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Read-only MCP server for Plausible Analytics that lets an assistant pull website traffic totals, breakdowns, trends and real-time visitor counts.

What you can do: Fetch aggregate site totals such as visitors, pageviews, bounce rate and visit duration
Segment metrics by pages, sources, countries, browsers, operating systems or devices
Retrieve historical timeseries points for charting and the current real-time visitor count
Test API connectivity and validate the configured token
List and read built-in analytics playbooks and check for package updates
When to use it: Useful when you want an assistant to answer questions about traffic on a Plausible Cloud or self-hosted site, produce quick reports or trend summaries, or check who is on the site right now, without opening the dashboard.
Requirements: Runs locally over stdio, typically via uvx (Python) or an npx bridge. Needs a Plausible Stats/Sites API token in PLAUSIBLE_API_KEY, or passed as a tool argument. PLAUSIBLE_BASE_URL is optional for self-hosted instances and defaults to Plausible Cloud. Network access to the Plausible instance is required.

Before you install

The API token grants access to your analytics data, so store it in the environment rather than in shared configs. The README mentions anonymous telemetry that is on by default and can be disabled with DO_NOT_TRACK=1. Tools are read-only, but site IDs and tokens are sent to the configured Plausible endpoint.

Installation

In SourceWeft

Open Plausible Analytics MCP in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

plausible-mcp

[PyPI version] [npm version] [License: MIT]

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)

Run with npx (Node / npm bridge)

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`)

json

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

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

Or using the npm bridge:

json

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

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

License

MIT License. See LICENSE for details.

Source: README.md at commit b20381a

Tools

get_aggregate_stats

Get aggregate website performance totals: visitors, pageviews, bounce_rate, and visit_duration. Args: site_id: Domain name of the site in Plausible (e.g. 'surendranb.com', 'freeinference.dev'). date_range: Time period ('day', 'today', 'yesterday', '7d', '30d', 'month', '6mo', '12mo', or 'YYYY-MM-DD,YYYY-MM-DD'). Default '30d'. metrics: Optional list of metrics (e.g. ['visitors', 'pageviews', 'bounce_rate', 'visit_duration', 'visits']). Defaults to standard 4 metrics. token: Optional Plausible API token. If omitted, uses PLAUSIBLE_API_KEY environment variable.

Parameterstokenmetricssite_idrequireddate_range

get_breakdown

Get metrics breakdown by dimension: pages, sources, countries, browsers, operating systems, or devices. Args: site_id: Domain name of the site in Plausible (e.g. 'surendranb.com'). property_name: Dimension to segment by. Accepts aliases: 'page', 'source', 'country', 'browser', 'os', 'device', 'entry_page', 'exit_page', 'city', 'region', or full Plausible names like 'event:page', 'visit:source'. date_range: Time period ('day', '7d', '30d', 'month', '6mo', '12mo', or 'YYYY-MM-DD,YYYY-MM-DD'). Default '30d'. limit: Maximum number of rows to return (default 20, max 100). token: Optional Plausible API token. If omitted, uses PLAUSIBLE_API_KEY environment variable.

Parameterslimittokensite_idrequireddate_rangeproperty_name

get_realtime_visitors

Get the current count of active real-time visitors on the website right now. Args: site_id: Domain name of the site in Plausible (e.g. 'surendranb.com'). token: Optional Plausible API token. If omitted, uses PLAUSIBLE_API_KEY environment variable.

Parameterstokensite_idrequired

get_timeseries

Get historical timeseries trendlines (visitors, pageviews) over time for plotting charts. Args: site_id: Domain name of the site in Plausible (e.g. 'surendranb.com'). date_range: Time period ('day', '7d', '30d', 'month', '6mo', '12mo', or 'YYYY-MM-DD,YYYY-MM-DD'). Default '30d'. interval: Aggregation bucket: 'date' (daily) or 'month' (monthly). Default 'date'. token: Optional Plausible API token. If omitted, uses PLAUSIBLE_API_KEY environment variable.

Parameterstokensite_idrequiredintervaldate_range

doctor

Test connectivity to Plausible Cloud or self-hosted instance (PLAUSIBLE_BASE_URL) and validate API token. Args: token: Optional Plausible API token to test. If omitted, tests PLAUSIBLE_API_KEY from environment.

Parameterstoken

skills_list

List available Plausible Analytics operational skills and playbooks.

Takes no parameters.

skill_read

Fetch guidance and analytical playbooks for Plausible Analytics by name. Args: name: Name of skill to read (e.g. 'plausible-overview', 'analytics-recipes'). Call skills_list() to view all.

Parametersnamerequired

check_for_updates

Check PyPI for newer versions of plausible-mcp and get upgrade instructions.