Skip to main content
Glama
arttus

umami-mcp-server

by arttus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Raw Umami API GET

umami_api_get
Read-onlyIdempotent

Retrieve raw JSON by making read-only GET requests to any Umami API endpoint that has no dedicated tool, including newer or custom endpoints like session data, reports, and teams.

Instructions

Make a read-only GET request against any Umami API endpoint that does not have a dedicated tool here.

Use this only as a fallback. The dedicated tools handle date parsing, website resolution, and formatting; this one does not. It is the right choice for endpoints such as /websites/:id/sessions/weekly, /websites/:id/session-data/properties, /websites/:id/session-data/values, /reports, /teams, /me, and anything added in a newer Umami release.

Timestamps in params must be epoch milliseconds, and website IDs must be UUIDs. Only GET is permitted, so this tool cannot create, update, or delete anything.

Args:

  • path (string, required): API path relative to the API root, for example '/websites/abc-123/sessions/weekly'. Do not include the /api prefix or the host.

  • params (object, optional): Query string parameters as string values, for example { startAt: '1735689600000', endAt: '1738368000000', timezone: 'America/New_York' }.

Returns: The raw JSON response from Umami, pretty-printed.

Examples:

  • Weekly session heatmap: path="/websites//sessions/weekly", params={ startAt: "...", endAt: "...", timezone: "America/New_York" }

  • Session property names: path="/websites//session-data/properties", params={ startAt: "...", endAt: "..." }

  • Current user: path="/me"

Error handling:

  • Rejects any path containing a query string; put parameters in 'params' instead.

  • Returns the Umami status code and path on failure, so a 404 usually means the endpoint does not exist on this Umami version.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesAPI path relative to the API root, starting with '/'. Example: '/websites/<uuid>/sessions/weekly'.
paramsNoQuery string parameters as string values.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A5/5.0
Behavior5/5

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

Beyond the annotations, the description discloses important behavior: it returns raw JSON pretty-printed, only permits GET, rejects query strings in the path, requires epoch-millisecond timestamps and UUID website IDs, and returns the Umami status code on failure. This substantially enriches the safety and expectations information carried by the annotations.

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

Conciseness5/5

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

The description is long but densely informative, with clear sections for purpose, usage, args, returns, examples, and error handling. The purpose and fallback guidance are front-loaded, and each sentence adds operational value rather than repeating structured metadata.

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

Completeness5/5

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

For a generic raw-API tool with no output schema, the description provides everything an agent needs to invoke it correctly: endpoint format, parameter constraints, return behavior, example calls, and error handling. It is complete enough to handle arbitrary new or undocumented endpoints using the same API surface.

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

Parameters5/5

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

Even though schema description coverage is 100%, the description adds meaningful semantics: it clarifies path is relative to API root, forbids '/api' prefix and embedded query strings, requires params values as strings, and gives several realistic examples with exact parameter shapes. This goes well beyond the schema's minimal descriptions.

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

Purpose5/5

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

The description states a precise verb and resource: 'Make a read-only GET request against any Umami API endpoint that does not have a dedicated tool here.' It clearly positions this tool as a general fallback, which differentiates it from the many dedicated sibling tools that wrap specific endpoints.

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

Usage Guidelines5/5

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

The description explicitly says to use this 'only as a fallback' and explains that dedicated tools handle date parsing, website resolution, and formatting while this one does not. It lists concrete example endpoints and mentions newer Umami endpoints, giving an agent clear selection criteria.

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