mcp-uptime-kuma

List Heartbeats

listHeartbeats

Fetch historical heartbeat data across all monitors to spot response-time trends, status changes, and event correlations. Returns newest-first, up to 100 per monitor.

Instructions

Retrieves historical heartbeat data for ALL monitors (response times, status changes over time). Use this for analyzing patterns across multiple monitors or correlating events. Beats are returned NEWEST-FIRST. By default returns only the most recent heartbeat per monitor; set maxHeartbeats (up to 100) for historical analysis. Keep maxHeartbeats ≤5 unless user requests more. Credentials embedded in a status message URL (user:pass@host) read "***" unless includeSecrets is set.

Input Schema

TableJSON Schema

Name	Required	Description
`count`	No	Alias for maxHeartbeats. Prefer maxHeartbeats.
`limit`	No	Alias for maxHeartbeats. Prefer maxHeartbeats.
`maxHeartbeats`	No	If set, returns the most recent X heartbeats per monitor (up to 100). If unset, returns only the most recent heartbeat per monitor (default: 1)
`includeSecrets`	No	Return credentials in full instead of "***". Off by default: this output is persisted in conversation transcripts and logs. Can also be enabled globally with UPTIME_KUMA_INCLUDE_SECRETS=true.

Output Schema

TableJSON Schema

Name	Required	Description
`heartbeats`	Yes	Map of monitor IDs to their heartbeat arrays
`monitorCount`	Yes
`totalHeartbeatCount`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.11.15Sep 9, 2026
- removedOutput schema / properties / heartbeats / additionalProperties / items / properties / msg / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  }
-]
```
- addedOutput schema / properties / heartbeats / additionalProperties / items / properties / msg / type
```
Added value: +"string"
```

Changed5 schema fields changedv0.11.9Aug 21, 2026

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 / count

Added value: +{
+  "description": "Alias for maxHeartbeats. Prefer maxHeartbeats.",
+  "exclusiveMinimum": 0,
+  "maximum": 100,
+  "type": "integer"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Alias for maxHeartbeats. Prefer maxHeartbeats.",
+  "exclusiveMinimum": 0,
+  "maximum": 100,
+  "type": "integer"
+}

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / properties / heartbeats / additionalProperties / items / properties / time / description

Previous value: -"Timestamp"New value: +"Timestamp, in UTC as \"YYYY-MM-DD HH:mm:ss.SSS\". Uptime Kuma sends no zone marker, so compare against the current UTC time, not local time."

First observedv0.0.0-devAug 7, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does an excellent job. It discloses return ordering ('NEWEST-FIRST'), default behavior (only most recent heartbeat per monitor), the max limit (up to 100), and the secret redaction behavior including the includeSecrets override and its privacy rationale. These are non-obvious behavioral traits that are critical for correct invocation.

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?

Four sentences pack in purpose, scope, ordering, default behavior, performance guidance, and a security caveat with no fluff. Every clause adds operational value, and the most important scoping information is front-loaded.

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 read-only-ish list tool with an output schema and zero required parameters, this description is exceptionally complete. It covers what data is returned, scope, ordering, defaults, limits, and secret handling. An agent has enough context to select and invoke the tool correctly without needing to inspect the schema or siblings.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds valuable context beyond the schema: the default of 1 heartbeat per monitor, the recommendation to keep maxHeartbeats at or below 5 unless requested, and the implication that count/limit are aliases of maxHeartbeats. This enriches the parameter understanding beyond field-level docs.

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 clearly states 'Retrieves historical heartbeat data for ALL monitors' with a specific verb, resource, and scope. It also specifies what data is included (response times, status changes over time), and the ALL-monitors scope distinguishes it from the sibling getHeartbeats without needing to open schemas.

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

Usage Guidelines4/5

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

It explicitly states when to use this tool: 'for analyzing patterns across multiple monitors or correlating events.' It also provides concrete usage guardrails like 'Keep maxHeartbeats ≤5 unless user requests more.' However, it does not explicitly name alternatives or describe when NOT to use it, so it falls short of a 5.

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