@iflow-mcp/alexanderop-plausible-mcp

v1.0.0

Published

23 days ago

An MCP server that provides access to Plausible Analytics API for querying website statistics

0High
0Medium
0Low

chatflowdev

qystart

mcp plausible analytics stats api model-context-protocol

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

Get your Plausible API key from https://plausible.io/settings/api-keys
Set up your .env file or VS Code/Claude config (see below)
Start the MCP server:
```
node build/index.js
```
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

Check if API key is set correctly
Verify network connectivity
For self-hosted instances, ensure PLAUSIBLE_API_URL is correct
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

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
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