Plausible Analytics MCP Server

Instructions

Implementation Reference

• src/index.ts:144-180 (handler)

  The handler for the 'get-timeseries' MCP tool is defined inline within src/index.ts. It processes the arguments, queries the Plausible client, and formats the results.

  server.tool(
    "get-timeseries",
    "Get traffic trends over time. Returns data points broken down by time interval (day, week, or month). Use this for trend analysis and charts.",
    {
      site_id: z.string().describe("Domain of the site (e.g. 'example.com')"),
      metrics: metricsSchema,
      date_range: dateRangeSchema,
      interval: z
        .enum(["date", "week", "month"])
        .describe("Time granularity for the series")
        .default("date"),
      filters: filtersSchema,
    },
    async ({ site_id, metrics, date_range, interval, filters }) => {
      const dimensionKey =
        interval === "date"
          ? "time:day"
          : interval === "week"
            ? "time:week"
            : "time:month";
  
      const result = await client.query({
        site_id,
        metrics,
        date_range,
        dimensions: [dimensionKey],
        filters: filters ?? undefined,
      });
  
      // Format as an array of { date, ...metrics }
      const rows = result.results.map((r) => {
        const row: Record<string, unknown> = { date: r.dimensions[0] };
        metrics.forEach((m, i) => {
          row[m] = r.metrics[i];
        });
        return row;
      });