plausible-mcp
# plausible-mcp
<!-- mcp-name: io.github.surendranb/plausible-mcp -->
[](https://pypi.org/project/plausible-mcp/)
[](https://www.npmjs.com/package/plausible-analytics-mcp)
[](LICENSE)
Fast, privacy-first [Plausible Analytics](https://plausible.io) 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)
```bash
export PLAUSIBLE_API_KEY="your_api_key_here"
uvx plausible-mcp
```
### Run with npx (Node / npm bridge)
```bash
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
1. Log in to Plausible (Cloud or your self-hosted instance).
2. Go to **Settings** (user profile menu) -> **API Keys**.
3. Click **+ New Key**, name it `mcp-agent`, and copy the token.
4. 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.
`site_id` is validated before any request leaves the process: only a bare domain (letters, digits,
dots, hyphens) is accepted. Schemes, slashes, colons, whitespace, IP literals, and traversal
segments return `[INPUT_FIXABLE] Invalid site_id` and make no outbound call.
## 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"
}
}
}
}
```
Or using the npm bridge:
```json
{
"mcpServers": {
"plausible": {
"command": "npx",
"args": ["-y", "plausible-analytics-mcp"],
"env": {
"PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
}
}
}
}
```
## License
MIT License. See [LICENSE](LICENSE) for details.
TDQS
Scored across 8 tools
Each analytics tool targets a clearly different output shape: totals (get_aggregate_stats), segmented rows (get_breakdown), trendlines (get_timeseries), and a live counter (get_realtime_visitors). The meta-tools are equally separable: skills_list vs skill_read differ by enumeration vs fetch, check_for_updates covers package versioning while doctor covers connectivity/auth. No two tools could plausibly be confused for the same task.
The dominant pattern is verb_noun (get_aggregate_stats, get_breakdown, get_timeseries, get_realtime_visitors, check_for_updates). The two skill tools invert to noun_verb (skills_list, skill_read) and 'doctor' is a bare noun, so there are minor deviations but everything remains readable and predictable.
Eight tools is a well-scoped set for an analytics server, and each one earns its place. However, three of the eight (skills_list, skill_read, check_for_updates, doctor) are operational/meta overhead, leaving only four actual analytics queries, which is a bit thin on the core surface.
The core read path (totals, breakdowns, timeseries, realtime) is covered, but the Plausible API surface is notably partial: no site/property listing, no goal or custom-event conversion metrics, no funnel or comparison queries, and no filter/segment parameters on breakdowns beyond a single dimension. Agents can work around some of this via date_range aliases but will hit dead ends on conversions and multi-dimensional filtering.