Plausible Analytics MCP Server

A Model Context Protocol (MCP) server that provides access to the Plausible Analytics API for querying website statistics and analytics data.

Features

• Full Plausible API Support: Query historical and real-time stats with filtering and dimensions
• Multiple Query Tools:
  • plausible_query: Full-featured querying with filters and dimensions
  • plausible_aggregate: Simple aggregate stats
  • plausible_breakdown: Stats broken down by dimensions
  • plausible_timeseries: Time-based data for charts
• Robust Error Handling: Automatic retries, timeout support, and detailed error messages
• Connection Testing: Built-in health check on startup
• Comprehensive Logging: Debug, info, and error logging through MCP

Prerequisites

• Node.js 16 or higher
• A Plausible Analytics account with API access
• Plausible API key (get from https://plausible.io/settings/api-keys)

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/plausible-mcp.git
cd plausible-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

From NPM (when published)

npm install -g @your-org/mcp-plausible

Configuration

Environment Variables

Create a .env file in the project root (see examples/.env.example):

# Required
PLAUSIBLE_API_KEY=your-api-key-here

# Optional
PLAUSIBLE_API_URL=https://plausible.io  # For self-hosted instances
PLAUSIBLE_TIMEOUT=30000                 # Request timeout in ms

VS Code Integration

For VS Code extensions that support MCP (like Cline), add to your settings:

{
  "cline.mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/absolute/path/to/plausible-mcp/build/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "${env:PLAUSIBLE_API_KEY}"
      }
    }
  }
}

See examples/vscode-settings.json for more configuration examples.

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/absolute/path/to/plausible-mcp/build/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

Once configured, the MCP server provides four main tools:

Getting Started

This MCP server lets you query Plausible Analytics for any site you own, directly from VS Code, Claude Desktop, or any MCP-compatible client. You can:

• Get traffic, engagement, and conversion stats for your site
• Break down analytics by page, device, country, source, and more
• Run advanced filters and time-based queries
• Automate reporting and SEO analysis

Quick Setup