@icjia/plausible-mcp
Provides tools for querying a self-hosted Plausible Analytics instance, including aggregate stats, top pages, traffic breakdown by source/country/device, timeseries trends, site discovery, and health checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@icjia/plausible-mcp show me the traffic overview for the past 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@icjia/plausible-mcp
Lightweight MCP server that queries a self-hosted Plausible Analytics instance and returns compressed, actionable results optimized for Claude's context window.
Built for ICJIA's 15+ state agency web properties monitored under a single Plausible CE instance at plausible.icjia.cloud.
Features
6 tools — overview, pages, breakdown, timeseries, site discovery, health check
Compressed output — structured plain text, 10-300 tokens per query instead of raw JSON
Computed deltas — period-over-period comparison on every overview query
Filters — human-readable syntax:
"page contains /grants","source is Google"Security-first — 12-layer security model including input validation, output sanitization, rate limiting, SSRF prevention, and prompt injection defense
90s response cache — reduces API load during iterative analysis
Zero build step — plain JavaScript ES modules, ships as-is to npm
Related MCP server: Plausible Analytics MCP Server
Requirements
Node.js >= 22 (see
.nvmrc)A self-hosted Plausible CE instance (uses the v1 Stats API — compatible with all versions)
A Plausible API key with Stats API scope
Getting your Plausible API key
Log into your Plausible instance (e.g.,
https://plausible.icjia.cloud)Go to Settings (your user settings, not site settings)
Scroll down to API Keys
Click + New API Key
Give it a name like "MCP Server"
Copy the key — you'll need it for configuration below
Your Plausible instance uses a single API key that covers all sites. There are no per-site keys.
Setup
Claude Code (terminal / CLI)
This is the easiest way to get started. Run this single command:
claude mcp add plausible-mcp -s user \
-e PLAUSIBLE_BASE_URL=https://plausible.icjia.cloud \
-e PLAUSIBLE_API_KEY=your-api-key-here \
-e PLAUSIBLE_DEFAULT_SITE=icjia.illinois.gov \
-- npx -y @icjia/plausible-mcpReplace:
https://plausible.icjia.cloudwith your Plausible instance URLyour-api-key-herewith your actual API keyicjia.illinois.govwith your most-used site domain (optional but recommended)
To verify it worked:
claude mcp listYou should see plausible-mcp in the list. Then in a Claude Code session, ask:
"What's the status of my Plausible connection?"
Claude will call the get_status tool and confirm connectivity.
Claude Code (Desktop App / claude.ai/code)
If you're using the Claude Code desktop app or web app, add the server through Settings > MCP Servers or edit your Claude Code config file directly.
Config file location:
macOS:
~/.claude/settings.jsonWindows:
%USERPROFILE%\.claude\settings.jsonLinux:
~/.claude/settings.json
Add this to your settings.json:
{
"mcpServers": {
"plausible-mcp": {
"command": "npx",
"args": ["-y", "@icjia/plausible-mcp"],
"env": {
"PLAUSIBLE_BASE_URL": "https://plausible.icjia.cloud",
"PLAUSIBLE_API_KEY": "your-api-key-here",
"PLAUSIBLE_DEFAULT_SITE": "icjia.illinois.gov"
}
}
}
}If you already have other MCP servers configured, add the
"plausible-mcp"block inside the existing"mcpServers"object — don't create a second one.
Cursor
Open Cursor's MCP settings:
Open Cursor Settings (Cmd+Shift+P → "Cursor Settings" or Cursor > Settings > Cursor Settings)
Click MCP in the left sidebar
Click + Add new MCP server
Enter:
Name:
plausible-mcpType:
commandCommand:
npx -y @icjia/plausible-mcp
Then add the environment variables. You can also edit the config file directly:
Config file location:
macOS:
~/.cursor/mcp.jsonWindows:
%USERPROFILE%\.cursor\mcp.jsonLinux:
~/.cursor/mcp.json
{
"mcpServers": {
"plausible-mcp": {
"command": "npx",
"args": ["-y", "@icjia/plausible-mcp"],
"env": {
"PLAUSIBLE_BASE_URL": "https://plausible.icjia.cloud",
"PLAUSIBLE_API_KEY": "your-api-key-here",
"PLAUSIBLE_DEFAULT_SITE": "icjia.illinois.gov"
}
}
}
}VS Code (Copilot / Continue / other MCP clients)
Most VS Code MCP extensions use a .vscode/mcp.json file in your project root, or a global settings file.
Project-level — create .vscode/mcp.json:
{
"servers": {
"plausible-mcp": {
"command": "npx",
"args": ["-y", "@icjia/plausible-mcp"],
"env": {
"PLAUSIBLE_BASE_URL": "https://plausible.icjia.cloud",
"PLAUSIBLE_API_KEY": "your-api-key-here",
"PLAUSIBLE_DEFAULT_SITE": "icjia.illinois.gov"
}
}
}
}Windsurf
Windsurf uses a ~/.windsurf/mcp.json config file:
{
"mcpServers": {
"plausible-mcp": {
"command": "npx",
"args": ["-y", "@icjia/plausible-mcp"],
"env": {
"PLAUSIBLE_BASE_URL": "https://plausible.icjia.cloud",
"PLAUSIBLE_API_KEY": "your-api-key-here",
"PLAUSIBLE_DEFAULT_SITE": "icjia.illinois.gov"
}
}
}
}Any MCP-compatible client
The server uses stdio transport (standard input/output). Any MCP client that can spawn a process and communicate via JSON-RPC over stdio will work. The configuration is always the same:
Command:
npxArgs:
["-y", "@icjia/plausible-mcp"]Environment variables:
Variable | Required | Description |
| Yes | Your Plausible instance URL (e.g., |
| Yes | Your Plausible Stats API key |
| No | Default site domain so you don't have to specify it every query |
Tools
Once configured, your AI assistant will have access to these 6 tools:
Tool | Purpose | Example question |
| Aggregate stats with computed deltas | "How's icjia.illinois.gov doing?" |
| Top or bottom pages by any metric | "What pages get the most traffic?" |
| Traffic by source, country, device, etc. | "Where's our traffic coming from?" |
| Trends over time | "Is traffic going up or down?" |
| Discover all sites on the instance | "What sites are we tracking?" |
| Server version + connectivity check | "Is the Plausible connection working?" |
Example output
icjia.illinois.gov [30d] Vis:12.4K(+8%) Sess:15.8K(+3%) PV:42.1K(-2%) Bounce:58.3%(+1.2pp) Dur:2m14s(+12%)Filters
All query tools support a human-readable filter string:
"page contains /grants"— pages with /grants in the path"source is Google"— traffic from Google only"device is Mobile"— mobile visitors only"country is US"— US visitors only"page is_not /"— exclude the homepage"source contains_not Direct"— exclude direct traffic
CLI
All tools are also available as standalone CLI commands (useful for scripting or testing):
# Set env vars first
export PLAUSIBLE_BASE_URL=https://plausible.icjia.cloud
export PLAUSIBLE_API_KEY=your-api-key-here
# Then run commands
npx @icjia/plausible-mcp overview icjia.illinois.gov
npx @icjia/plausible-mcp pages icjia.illinois.gov --sort asc --limit 5
npx @icjia/plausible-mcp breakdown icjia.illinois.gov --dimension visit:source
npx @icjia/plausible-mcp timeseries icjia.illinois.gov --period 6mo
npx @icjia/plausible-mcp list-sites
npx @icjia/plausible-mcp statusRunning without a subcommand starts the MCP server (stdio mode).
Security
12-layer security model. See docs/doc-00-master-design.md for full details.
Input validation — allowlists and length caps on all parameters
Output sanitization — prompt injection prevention on all Plausible-sourced strings
Rate limiting — 600/hr, 3 concurrent, 15s timeout
Response safety — 5MB body cap, schema validation
Error sanitization — actionable messages, no key leakage
Base URL validation — SSRF prevention
Content-Type validation — catches DNS rebinding / proxy misconfiguration
Cache integrity — only validated responses cached
Static code constraints — no eval, no dynamic import
API key protection — masked everywhere, never in output
Dependency pinning — exact versions, lockfile committed
Transport isolation — stdio only, no open ports
Troubleshooting
"Authentication failed"
Your API key is wrong or missing. Double-check PLAUSIBLE_API_KEY.
"Endpoint not found (404)"
The API endpoint wasn't found. Verify PLAUSIBLE_BASE_URL is correct.
"Cannot connect to Plausible"
Check that PLAUSIBLE_BASE_URL is correct and the instance is running. Try opening the URL in a browser.
"Sites API not available (403)"
The list_sites tool requires the Sites API scope. Other tools will still work. You can list your sites manually.
Server not showing up in Claude Code
Run claude mcp list to verify registration. If missing, re-run the claude mcp add command.
Development
git clone https://github.com/ICJIA/plausible-mcp.git
cd plausible-mcp
nvm use
npm install
npm testLicense
MIT - see LICENSE.
Available Tools
6 toolsget_statusA
Server info, version, and Plausible instance health check.
Inputs: no named parameters.
list_sitesA
Discover all sites tracked by the Plausible instance.
Inputs: no named parameters.
query_breakdownA
Break down traffic by any dimension: source, country, device, browser, OS, UTMs, etc.
Inputs: dimension (required), sort, limit, filter, +4 more.
query_overviewA
Aggregate stats for a site with period-over-period deltas. Answers "How is this site doing?"
Inputs: filter, period, siteId, metrics, +1 more.
query_pagesA
Top or bottom pages by traffic. Answers "What pages are popular?" or "What pages get no traffic?"
Inputs: sort, limit, filter, period, +3 more.
query_timeseriesC
Trend data over time. Answers "Is traffic going up or down?"
Inputs: filter, period, siteId, metrics, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: server info, site listing, dimension breakdown, aggregate stats, page rankings, and time trends. No overlap.
All tools follow a consistent verb_noun pattern (get_status, list_sites, query_breakdown, etc.), making the API predictable.
Six tools is appropriate for a Plausible analytics client, covering all essential read operations without excess.
The tool surface covers server health, site listing, and all major query types (dimension breakdown, overview with deltas, pages, timeseries). No obvious gaps for a read-only analytics tool.
Maintenance
Related MCP Connectors
Query site stats, realtime visitors, breakdowns and goals from Plausible Analytics.
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
Read your cookieless, EU-hosted web analytics: visitors, sources, pages, goals and live. Read-only.
Read Pirsch web analytics: visitors, pages, referrers, UTM, events, funnels and sessions.
Related MCP Servers
- AlicenseBqualityDmaintenanceAllows AI models to query and retrieve analytics data from Plausible Analytics through the Plausible API, enabling natural language interactions with website statistics.18MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to query website statistics from Plausible Analytics, providing access to metrics like real-time visitors, traffic trends, and page performance. It supports both Plausible Cloud and self-hosted instances through the Stats API v2.642 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying Plausible Analytics data for website statistics, traffic, engagement, and conversions through natural language, with support for filters, dimensions, and time-series.6MIT
- AlicenseBqualityDmaintenanceEnables natural language interaction with Plausible Analytics data to query traffic, visitors, engagement, and more using conversational questions.41MIT