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

1. Get your Plausible API key from https://plausible.io/settings/api-keys
2. Set up your .env file or VS Code/Claude config (see below)
3. Start the MCP server:

   node build/index.js
   

4. Connect with your MCP client and start querying!

Example Queries

Get traffic stats for your site

{
  "site_id": "alexop.dev",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "30d"
}

See top countries and devices

{
  "site_id": "alexop.dev",
  "metrics": ["visitors"],
  "date_range": "30d",
  "dimensions": ["visit:country_name", "visit:device"]
}

Analyze traffic sources and campaigns

{
  "site_id": "alexop.dev",
  "metrics": ["visitors"],
  "date_range": "30d",
  "dimensions": ["visit:source", "visit:utm_campaign"]
}

Get hourly traffic trends

{
  "site_id": "alexop.dev",
  "metrics": ["pageviews"],
  "date_range": "7d",
  "dimensions": ["time:hour"]
}

Conversion rate by source (if goals set)

{
  "site_id": "alexop.dev",
  "metrics": ["conversion_rate"],
  "date_range": "30d",
  "dimensions": ["visit:source"]
}

Scroll depth per page

{
  "site_id": "alexop.dev",
  "metrics": ["scroll_depth"],
  "date_range": "30d",
  "dimensions": ["event:page"]
}

What insights can you get?

• Top pages, landing and exit pages
• Device, browser, and OS breakdowns
• Geographic breakdowns (country, region, city)
• Traffic sources and UTM campaign performance
• Conversion rates and custom event tracking
• Scroll depth and time on page
• Hourly/daily/weekly/monthly traffic trends
• Advanced filters and segments

1. plausible_query

Full-featured querying with all Plausible API capabilities:

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "7d",
  "filters": [
    ["is", "visit:country_name", ["United States", "Canada"]]
  ],
  "dimensions": ["visit:source"],
  "order_by": [["visitors", "desc"]],
  "pagination": { "limit": 10 }
}

2. plausible_aggregate

Simple aggregate stats without dimensions:

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews"],
  "date_range": "month"
}

3. plausible_breakdown

Stats broken down by dimensions:

{
  "site_id": "example.com",
  "metrics": ["visitors"],
  "date_range": "7d",
  "dimensions": ["visit:country_name", "visit:device"],
  "limit": 20
}

4. plausible_timeseries

Time-based data for charts:

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews"],
  "date_range": "30d",
  "interval": "time:day"
}

API Reference

Date Ranges

• Relative: "day", "7d", "30d", "month", "6mo", "12mo", "year", "all"
• Custom: ["2024-01-01", "2024-01-31"] (ISO 8601 format)

Metrics

• Traffic: visitors, visits, pageviews, views_per_visit
• Engagement: bounce_rate, visit_duration, scroll_depth
• Events: events, conversion_rate, group_conversion_rate
• Revenue: average_revenue, total_revenue
• Other: percentage, time_on_page

Dimensions

Visit Dimensions

• visit:source - Traffic source
• visit:referrer - Referrer URL
• visit:utm_medium - UTM medium
• visit:utm_source - UTM source
• visit:utm_campaign - UTM campaign
• visit:utm_content - UTM content
• visit:utm_term - UTM term
• visit:device - Device type
• visit:browser - Browser name
• visit:browser_version - Browser version
• visit:os - Operating system
• visit:os_version - OS version
• visit:country - Country code
• visit:country_name - Country name
• visit:region - Region code
• visit:region_name - Region name
• visit:city - City code
• visit:city_name - City name

Event Dimensions

• event:page - Page path
• event:hostname - Hostname
• event:goal - Goal name
• event:props:* - Custom properties

Time Dimensions

• time - Auto-detected
• time:hour - Hourly
• time:day - Daily
• time:week - Weekly
• time:month - Monthly

Filters

Simple Filters

["is", "visit:country", ["US", "CA"]]
["contains", "event:page", ["/blog/"]]
["matches", "visit:source", ["google.*"]]

Logical Filters

["and", [
  ["is", "visit:device", ["Mobile"]],
  ["is", "visit:country", ["US"]]
]]

["or", [
  ["is", "visit:source", ["google"]],
  ["is", "visit:source", ["bing"]]
]]

["not", ["is", "visit:country", ["US"]]]

Behavioral Filters

["has_done", ["is", "event:goal", ["Signup"]]]
["has_not_done", ["is", "event:goal", ["Purchase"]]]

Advanced Features

Error Handling

• Automatic Retries: Failed requests are retried up to 3 times with exponential backoff
• Rate Limit Handling: Respects Retry-After headers from Plausible API
• Timeout Support: Configurable request timeout (default 30s)
• Detailed Error Messages: Clear error messages with context

Logging

The server logs important events:

• Connection status on startup
• Tool invocations with parameters
• Success/failure of queries
• Detailed error information

To view logs:

• Claude Desktop: tail -f ~/Library/Logs/Claude/mcp*.log (macOS)
• VS Code: Check extension output panel

Development

# Install dependencies
npm install

# Run TypeScript compiler in watch mode
npm run build -- --watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run typecheck

Troubleshooting

Connection Issues

1. Check if API key is set correctly
2. Verify network connectivity
3. For self-hosted instances, ensure PLAUSIBLE_API_URL is correct
4. Check logs for detailed error messages

Rate Limiting

• Default limit: 600 requests/hour
• Server automatically retries with backoff
• Check Retry-After header in logs

Common Errors

• "Authentication failed": Invalid API key
• "Not found": Site doesn't exist or you don't have access
• "Bad request": Check query parameters format

Security

• Never commit API keys to version control
• Use environment variables for sensitive data
• Consider using secret management tools for production
• All inputs are validated before sending to API

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT - See LICENSE file for details

Support

• Plausible API Docs: https://plausible.io/docs/stats-api
• MCP Documentation: https://modelcontextprotocol.io
• Issues: https://github.com/yourusername/plausible-mcp/issues

Changelog

1.0.0

• Initial release with full Plausible Stats API support
• Four specialized tools for different query types
• Robust error handling and retry logic
• Comprehensive logging through MCP
• Connection health check on startup