Skip to main content
Glama
Sign In
plausible-mcp

plausible-mcp

by getsentry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Get Breakdown

get_breakdown
Read-onlyIdempotent

Break down Plausible metrics by page, traffic source, country, device, or other dimensions to identify top pages, sources, and traffic segments.

Instructions

Break down metrics by a dimension: page, traffic source, country, device, etc. Use to find top pages, sources, or segment traffic.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site_id": "<site_id>",
      "date_range": "<date_range>",
      "dimension": "<dimension>"
    },
    "name": "get_breakdown"
  }
}

Input Schema

NameRequiredDescriptionDefault
goalNoFilter by goal name (e.g. Signup, Purchase). Do not also target event:goal in property_filters; the call is rejected.
pageNoFilter by page path. Exact match by default, use * as trailing wildcard (e.g. /blog*). Do not also target event:page in property_filters; the call is rejected.
limitNoMax results to return per page. Use offset to fetch further pages; pagination.has_more in the result says whether more rows exist.
offsetNoNumber of rows to skip, for paging past the first `limit` rows
metricsNoMetrics to return. Defaults vary by tool. Plausible rejects these combinations: bounce_rate or visit_duration with event:goal or event:props:<name> dimensions; pageviews, events, scroll_depth or time_on_page with visit:entry_page or visit:exit_page dimensions; views_per_visit with any non-time dimension or a page filter. For goal conversions use get_conversions.
site_idYesPlausible site domain (e.g. example.com). Required.
dimensionYesDimension to group results by: a standard dimension (e.g. event:page, visit:source), or a custom event property as "event:props:<name>" (e.g. event:props:plan). Prefer visit:country_name/region_name/city_name over the code variants when presenting geography to people. An empty visit:entry_page or visit:exit_page value means a session with no recorded pageview.
date_rangeYesDate range: "1h", "24h" (last N hours, ending now), "7d", "30d", "12mo", "month", "year", "all", "YYYY-MM-DD,YYYY-MM-DD" (start,end, both inclusive), or "YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ" for a sub-day window (any offset, e.g. +02:00). Days after today count as zero.
property_filtersNoFilter results by built-in dimensions or custom event properties, e.g. [{ "property": "visit:channel", "operator": "is", "values": ["Organic Search"] }] or [{ "property": "plan", "values": ["pro"] }]. Entries are combined with AND.

Output Schema

NameRequiredDescriptionDefault
metricsYesMetric keys, in the order they appear in each row's `metrics` array
resultsYesOne row per dimension-value combination returned by Plausible
dimensionsYesDimension keys, in the order they appear in each row's `dimensions` array
paginationNoPresent only on paged tools (get_breakdown)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.12.2
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed1 schema field changedv0.11.3
    • addedInput schema / properties / goal
      Added value: +{
+  "description": "Filter by goal name (e.g. Signup, Purchase). Do not also target event:goal in property_filters; the call is rejected.",
+  "maxLength": 1024,
+  "type": "string"
+}
  3. Changed8 schema fields changedv0.10.0
    • changedInput schema / properties / date_range / description
      Previous value: -"Date range: \"7d\", \"30d\", \"12mo\", \"month\", \"year\", \"all\", or \"YYYY-MM-DD,YYYY-MM-DD\""New value: +"Date range: \"1h\", \"24h\" (last N hours, ending now), \"7d\", \"30d\", \"12mo\", \"month\", \"year\", \"all\", \"YYYY-MM-DD,YYYY-MM-DD\" (start,end, both inclusive), or \"YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ\" for a sub-day window (any offset, e.g. +02:00). Days after today count as zero."
    • changedInput schema / properties / date_range / pattern
      Previous value: -"^(\\d+h|\\d+d|\\d+mo|day|month|year|all|\\d{4}-\\d{2}-\\d{2},\\d{4}-\\d{2}-\\d{2})$"New value: +"^(\\d+h|\\d+d|\\d+mo|day|month|year|all|\\d{4}-\\d{2}-\\d{2},\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2}),\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2}))$"
    • changedInput schema / properties / dimension / description
      Previous value: -"Dimension to group results by: a standard dimension (e.g. event:page, visit:source), or a custom event property as \"event:props:<name>\" (e.g. event:props:plan)."New value: +"Dimension to group results by: a standard dimension (e.g. event:page, visit:source), or a custom event property as \"event:props:<name>\" (e.g. event:props:plan). Prefer visit:country_name/region_name/city_name over the code variants when presenting geography to people. An empty visit:entry_page or visit:exit_page value means a session with no recorded pageview."
    • changedInput schema / properties / limit / description
      Previous value: -"Max results to return"New value: +"Max results to return per page. Use offset to fetch further pages; pagination.has_more in the result says whether more rows exist."
    • changedInput schema / properties / metrics / description
      Previous value: -"Metrics to return. Defaults vary by tool."New value: +"Metrics to return. Defaults vary by tool. Plausible rejects these combinations: bounce_rate or visit_duration with event:goal or event:props:<name> dimensions; pageviews, events, scroll_depth or time_on_page with visit:entry_page or visit:exit_page dimensions; views_per_visit with any non-time dimension or a page filter. For goal conversions use get_conversions."
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Number of rows to skip, for paging past the first `limit` rows",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • changedInput schema / properties / page / description
      Previous value: -"Filter by page path. Exact match by default, use * as trailing wildcard (e.g. /blog*)"New value: +"Filter by page path. Exact match by default, use * as trailing wildcard (e.g. /blog*). Do not also target event:page in property_filters; the call is rejected."
    • addedOutput schema / properties / pagination
      Added value: +{
+  "additionalProperties": false,
+  "description": "Present only on paged tools (get_breakdown)",
+  "properties": {
+    "has_more": {
+      "description": "True when rows exist beyond this page",
+      "type": "boolean"
+    },
+    "limit": {
+      "description": "Max rows requested",
+      "type": "number"
+    },
+    "offset": {
+      "description": "Rows skipped before the first returned row",
+      "type": "number"
+    }
+  },
+  "required": [
+    "limit",
+    "offset",
+    "has_more"
+  ],
+  "type": "object"
+}
  4. Changed4 schema fields changedv0.9.0
    • removedOutput schema / properties / results / items / properties / dimensions / items / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
    • addedOutput schema / properties / results / items / properties / dimensions / items / type
      Added value: +[
+  "string",
+  "number"
+]
    • removedOutput schema / properties / results / items / properties / metrics / items / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / results / items / properties / metrics / items / type
      Added value: +[
+  "number",
+  "string",
+  "null"
+]
  5. Changed1 schema field changedv0.7.2
    • addedInput schema / properties / property_filters / items / properties / values / items / maxLength
      Added value: +1024
  6. Changed9 schema fields changedv0.7.1
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / dimension / anyOf
      Added value: +[
+  {
+    "enum": [
+      "event:page",
+      "event:goal",
+      "event:hostname",
+      "visit:entry_page",
+      "visit:exit_page",
+      "visit:source",
+      "visit:referrer",
+      "visit:channel",
+      "visit:utm_medium",
+      "visit:utm_source",
+      "visit:utm_campaign",
+      "visit:utm_content",
+      "visit:utm_term",
+      "visit:device",
+      "visit:browser",
+      "visit:browser_version",
+      "visit:os",
+      "visit:os_version",
+      "visit:country",
+      "visit:region",
+      "visit:city",
+      "visit:country_name",
+      "visit:region_name",
+      "visit:city_name"
+    ],
+    "type": "string"
+  },
+  {
+    "maxLength": 312,
+    "minLength": 13,
+    "pattern": "^event:props:",
+    "type": "string"
+  }
+]
    • changedInput schema / properties / dimension / description
      Previous value: -"Dimension to group results by"New value: +"Dimension to group results by: a standard dimension (e.g. event:page, visit:source), or a custom event property as \"event:props:<name>\" (e.g. event:props:plan)."
    • removedInput schema / properties / dimension / enum
      Removed value: -[
-  "event:page",
-  "event:goal",
-  "event:hostname",
-  "visit:entry_page",
-  "visit:exit_page",
-  "visit:source",
-  "visit:referrer",
-  "visit:channel",
-  "visit:utm_medium",
-  "visit:utm_source",
-  "visit:utm_campaign",
-  "visit:utm_content",
-  "visit:utm_term",
-  "visit:device",
-  "visit:browser",
-  "visit:browser_version",
-  "visit:os",
-  "visit:os_version",
-  "visit:country",
-  "visit:region",
-  "visit:city",
-  "visit:country_name",
-  "visit:region_name",
-  "visit:city_name"
-]
    • removedInput schema / properties / dimension / type
      Removed value: -"string"
    • addedInput schema / properties / property_filters
      Added value: +{
+  "description": "Filter results by built-in dimensions or custom event properties, e.g. [{ \"property\": \"visit:channel\", \"operator\": \"is\", \"values\": [\"Organic Search\"] }] or [{ \"property\": \"plan\", \"values\": [\"pro\"] }]. Entries are combined with AND.",
+  "items": {
+    "properties": {
+      "operator": {
+        "default": "is",
+        "description": "Match operator: is, is_not, contains, contains_not (default: is)",
+        "enum": [
+          "is",
+          "is_not",
+          "contains",
+          "contains_not"
+        ],
+        "type": "string"
+      },
+      "property": {
+        "description": "What to filter on: a built-in dimension (e.g. \"visit:channel\", \"visit:source\", \"event:page\") or a custom event property as its bare name (e.g. \"plan\" targets event:props:plan)",
+        "maxLength": 312,
+        "minLength": 1,
+        "type": "string"
+      },
+      "values": {
+        "description": "One or more values to match the property against",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "property",
+      "values"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / site_id / description
      Previous value: -"Plausible site domain (e.g. example.com). Uses PLAUSIBLE_DEFAULT_SITE_ID if omitted."New value: +"Plausible site domain (e.g. example.com). Required."
    • changedInput schema / required
      Previous value: -[
-  "date_range",
-  "dimension"
-]New value: +[
+  "site_id",
+  "date_range",
+  "dimension"
+]
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  7. First observedv0.5.1

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered by structured data. The description adds nothing behavioral beyond that: no note on default limits/pagination, no mention that metric+dimension combinations are rejected, no statement about ordering or result shape, all of which matter for a 9-parameter analytics query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action, no filler or repetition. It is appropriately sized for a description that is deliberately leaving detail to a rich schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema and full annotation set exist, so return values and safety need not be re-explained. However, for a tool with 9 parameters and non-obvious validation rules (mutually exclusive metric/dimension pairs, filter double-targeting), the description does not warn the agent that naive metric/dimension pairings fail, leaving that discovery entirely to schema reading.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented (date_range formats, property_filters combining with AND, metric/dimension conflicts). The description only loosely maps colloquial terms ("page", "traffic source", "country", "device") to the underlying dimension names without disambiguating event:page vs visit:entry_page or visit:country vs visit:country_name, so it adds marginal meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Break down metrics by a dimension") and enumerates example dimensions (page, traffic source, country, device) plus the analytical intent ("find top pages, sources, or segment traffic"). It is clearly distinct from get_timeseries/compare_periods/get_conversions by implication, but never names a sibling or routing condition, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use to find top pages, sources, or segment traffic" gives a positive usage context, but there is no when-not guidance and no pointer to the alternative tools (get_timeseries, compare_periods, get_conversions) that an agent must choose between. The only routing advice ("For goal conversions use get_conversions") lives in the schema, not the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools