Plausible MCP Server

Instructions

Implementation Reference

• src/index.ts:39-54 (handler)

  Handler logic for the plausible_query tool in the CallToolRequest handler. Validates input arguments and delegates to plausibleClient.query.
  case "plausible_query": { const args = request.params.arguments as unknown as QueryArgs; if (!args.site_id || !args.metrics || !args.date_range) { throw new Error( "Missing required arguments: site_id, metrics, and date_range" ); } const response = await plausibleClient.query( args.site_id, args.metrics, args.date_range ); return { content: [{ type: "text", text: JSON.stringify(response) }], }; }
• src/plausible/query.ts:9-35 (schema)

  Tool schema definition for plausible_query, including input schema with properties for site_id, metrics, and date_range.
  export const queryTool: Tool = { name: "plausible_query", description: "Query analytics data from Plausible", inputSchema: { type: "object", required: ["site_id", "metrics", "date_range"], properties: { site_id: { type: "string", description: "The domain of the site to query data for", }, metrics: { type: "array", items: { type: "string", }, description: "String list of metrics to query with the following options: 'visitors' 'int' The number of unique visitors | 'visits' 'int' The number of visits/sessions | 'pageviews' 'int' The number of pageview events | 'views_per_visit' 'float' The number of pageviews divided by the number of visits. | 'bounce_rate' 'float' Bounce rate percentage | 'visit_duration' 'int' Visit duration in seconds | 'events' 'int' The number of events (pageviews + custom events). When filtering by a goal, this metric corresponds to 'Total Conversions' in the dashboard. | 'scroll_depth' 'int' Page scroll depth averaged per session Requires event:page filter or dimension being set | 'percentage' 'float' The percentage of visitors of total who fall into this category Requires non-empty dimensions | 'conversion_rate' 'float' The percentage of visitors who completed the goal. Requires non-empty dimensions, event:goal filter or dimension being set | 'group_conversion_rate' 'float' The percentage of visitors who completed the goal with the same dimension. Requires: dimension list passed, an event:goal filter or event:goal dimension Requires non-empty dimensions, event:goal filter or dimension being set | 'average_revenue' 'Revenue' or null Average revenue per revenue goal conversion Requires revenue goals, event:goal filter or dimension for a relevant revenue goal. | 'total_revenue' 'Revenue' or null Total revenue from revenue goal conversions Requires revenue goals, event:goal filter or dimension for a relevant revenue goal.", }, date_range: { type: "string", description: 'Date range for the query, with the following options: ["2024-01-01", "2024-07-01"] Custom date range (ISO8601) | ["2024-01-01T12:00:00+02:00", "2024-01-01T15:59:59+02:00"] Custom date-time range (ISO8601) | "day" Current day (e.g. 2024-07-01) | "7d" Last 7 days relative to today | "30d" Last 30 days relative to today | "month" Since the start of the current month | "6mo" Last 6 months relative to start of this month | "12mo" Last 12 months relative to start of this month | "year" Since the start of this year | "all"', }, }, }, };
• src/index.ts:24-28 (registration)

  Registration of the plausible_query tool in the ListToolsRequestHandler.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [queryTool], }; });
• src/plausible/client.ts:10-29 (helper)

  Core implementation of the query logic in PlausibleClient, performing the POST request to the Plausible API.
  async query(siteId: string, metrics: string[], dateRange: string) { const response = await fetch(`${PLAUSIBLE_API_URL}/query`, { method: "POST", headers: { Authorization: `Bearer ${PLAUSIBLE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ site_id: siteId, metrics: metrics, date_range: dateRange, }), }); if (!response.ok) { throw new Error(`Plausible API error: ${response.statusText}`); } return response.json(); }