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

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

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.