plausible

This Plausible Analytics MCP Server exposes a set of tools that allow you to query Plausible Analytics data directly from MCP-enabled clients (such as VS Code integrations or Claude Desktop). The server provides four main tools: plausible_query for full-featured querying with filters and dimensions, plausible_aggregate for simple aggregate statistics, plausible_breakdown for breaking down metrics by dimensions (e.g., country, device), and plausible_timeseries for time-based data suitable for charts. With proper API keys and access, you can retrieve traffic, engagement, conversions, and other Plausible metrics across sites you manage. The server supports robust error handling, automatic retries, and configurable timeouts to help ensure reliable data access in automation or IDE workflows.

Prerequisites:

• Node.js 16 or higher
• A Plausible Analytics account with API access
• Plausible API key

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 (if applicable)
npm run build

From NPM (when published):

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

Configuration (environment):

• 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

Running the server:

node build/index.js

(or use whatever npm script you have to start the server in development or production).

Environment variables:

• PLAUSIBLE_API_KEY is required to access Plausible API.
• PLAUSIBLE_API_URL can be set if you use a self-hosted Plausible instance.
• PLAUSIBLE_TIMEOUT configures request timeout in milliseconds.

Common issues:

• Ensure the Plausible API key has read permissions for the sites you query.
• If you see rate-limit errors, the server will retry with backoff; consider increasing PLAUSIBLE_TIMEOUT if requests intermittently fail.
• When running in IDE integrations, provide absolute paths to the built server bundle (e.g., build/index.js).

Configuration options:

• You can adjust the env block for the MCP server to pass API keys and timeouts to the process.
• In IDE integrations, mappings for server names (like plausible) should reflect the mcpServers keys.

NPM package:

• If you publish, the package name would be something like @your-org/mcp-plausible. Current README examples show using the global install with that package name.