Problem
The get_breakdown tool currently exposes visit:city, visit:region, and visit:country — but Plausible returns these as GeoNames numeric IDs (e.g. 2657896 for Zürich), not human-readable names. This makes the tool's output unusable in MCP clients like Claude / Cowork without a separate ID-to-name lookup step.
Example output today (top city for a real site, last 30d):
{ "metrics": [190, 652, 53], "dimensions": [2657896] }The Plausible Stats API v2 supports the _name variants (visit:city_name, visit:region_name, visit:country_name) which return strings:
{ "metrics": [190, 652, 53], "dimensions": ["Zürich", "Switzerland"] }These are not in VALID_DIMENSIONS (src/schemas.ts#L20-L42), so MCP clients can't request them.
Proposed change
Add the three _name dimensions to VALID_DIMENSIONS:
export const VALID_DIMENSIONS = [
// ...existing entries
"visit:country",
"visit:country_name",
"visit:region",
"visit:region_name",
"visit:city",
"visit:city_name",
] as const;
No other code changes needed — Plausible accepts these dimensions identically; the server already passes them through to /api/v2/query.
Verified
Tested directly against https://plausible.io/api/v2/query with a real Stats API key — all three _name dimensions are accepted and return readable strings on a Business plan.
Happy to PR
If welcome, I can submit a PR with the schema change + a small test in src/schemas.test.ts (or wherever the existing dimension tests live).
Problem
The
get_breakdowntool currently exposesvisit:city,visit:region, andvisit:country— but Plausible returns these as GeoNames numeric IDs (e.g.2657896for Zürich), not human-readable names. This makes the tool's output unusable in MCP clients like Claude / Cowork without a separate ID-to-name lookup step.Example output today (top city for a real site, last 30d):
{ "metrics": [190, 652, 53], "dimensions": [2657896] }The Plausible Stats API v2 supports the
_namevariants (visit:city_name,visit:region_name,visit:country_name) which return strings:{ "metrics": [190, 652, 53], "dimensions": ["Zürich", "Switzerland"] }These are not in
VALID_DIMENSIONS(src/schemas.ts#L20-L42), so MCP clients can't request them.Proposed change
Add the three
_namedimensions toVALID_DIMENSIONS:No other code changes needed — Plausible accepts these dimensions identically; the server already passes them through to
/api/v2/query.Verified
Tested directly against
https://plausible.io/api/v2/querywith a real Stats API key — all three_namedimensions are accepted and return readable strings on a Business plan.Happy to PR
If welcome, I can submit a PR with the schema change + a small test in
src/schemas.test.ts(or wherever the existing dimension tests live).