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.
