@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

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

1. Log into your Plausible instance (e.g., https://plausible.icjia.cloud)
2. Go to Settings (your user settings, not site settings)
3. Scroll down to API Keys
4. Click + New API Key
5. Give it a name like "MCP Server"
6. 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-mcp

Replace:

• https://plausible.icjia.cloud with your Plausible instance URL
• your-api-key-here with your actual API key
• icjia.illinois.gov with your most-used site domain (optional but recommended)

To verify it worked:

claude mcp list

You 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.json
• Windows: %USERPROFILE%\.claude\settings.json
• Linux: ~/.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:

1. Open Cursor Settings (Cmd+Shift+P → "Cursor Settings" or Cursor > Settings > Cursor Settings)
2. Click MCP in the left sidebar
3. Click + Add new MCP server
4. Enter:
   • Name: plausible-mcp
   • Type: command
   • Command: npx -y @icjia/plausible-mcp

Then add the environment variables. You can also edit the config file directly:

Config file location:

• macOS: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json
• Linux: ~/.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: npx
• Args: ["-y", "@icjia/plausible-mcp"]
• Environment variables:

| Variable | Required | Description | |---|---|---| | PLAUSIBLE_BASE_URL | Yes | Your Plausible instance URL (e.g., https://plausible.icjia.cloud) | | PLAUSIBLE_API_KEY | Yes | Your Plausible Stats API key | | PLAUSIBLE_DEFAULT_SITE | 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 | |---|---|---| | query_overview | Aggregate stats with computed deltas | "How's icjia.illinois.gov doing?" | | query_pages | Top or bottom pages by any metric | "What pages get the most traffic?" | | query_breakdown | Traffic by source, country, device, etc. | "Where's our traffic coming from?" | | query_timeseries | Trends over time | "Is traffic going up or down?" | | list_sites | Discover all sites on the instance | "What sites are we tracking?" | | get_status | 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 status

Running without a subcommand starts the MCP server (stdio mode).

Security

12-layer security model. See docs/doc-00-master-design.md for full details.

1. Input validation — allowlists and length caps on all parameters
2. Output sanitization — prompt injection prevention on all Plausible-sourced strings
3. Rate limiting — 600/hr, 3 concurrent, 15s timeout
4. Response safety — 5MB body cap, schema validation
5. Error sanitization — actionable messages, no key leakage
6. Base URL validation — SSRF prevention
7. Content-Type validation — catches DNS rebinding / proxy misconfiguration
8. Cache integrity — only validated responses cached
9. Static code constraints — no eval, no dynamic import
10. API key protection — masked everywhere, never in output
11. Dependency pinning — exact versions, lockfile committed
12. 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 test

License

MIT - see LICENSE.