Plausible Analytics MCP Server

Instructions

Implementation Reference

• src/index.ts:112-139 (handler)

  The handler function for the get-aggregate-stats tool that queries the client and formats the response.

  async ({ site_id, metrics, date_range, filters }) => {
    const result = await client.query({
      site_id,
      metrics,
      date_range,
      filters: filters ?? undefined,
    });
  
    // Format the aggregate result readably
    const row = result.results[0];
    const formatted: Record<string, unknown> = {};
    metrics.forEach((m, i) => {
      formatted[m] = row?.metrics[i];
    });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            { site_id, date_range, metrics: formatted },
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:103-140 (registration)

  The MCP tool registration for 'get-aggregate-stats' including input schema definitions.

  server.tool(
    "get-aggregate-stats",
    "Get aggregate stats for a site over a time period (visitors, pageviews, bounce rate, etc.). Use this for summary/overview questions.",
    {
      site_id: z.string().describe("Domain of the site (e.g. 'example.com')"),
      metrics: metricsSchema,
      date_range: dateRangeSchema,
      filters: filtersSchema,
    },
    async ({ site_id, metrics, date_range, filters }) => {
      const result = await client.query({
        site_id,
        metrics,
        date_range,
        filters: filters ?? undefined,
      });
  
      // Format the aggregate result readably
      const row = result.results[0];
      const formatted: Record<string, unknown> = {};
      metrics.forEach((m, i) => {
        formatted[m] = row?.metrics[i];
      });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              { site_id, date_range, metrics: formatted },
              null,
              2
            ),
          },
        ],
      };
    }
  );