UniFi Network MCP Server

Overview Schema Source Related Servers Discussions Admin

List client history

unifi_list_client_history

Read-only

Retrieve offline UniFi client inventory for a site to identify disconnected devices. Returns MACs, names, first/last seen times, wired status, and total count.

Instructions

List historical/offline client inventory using the controller v2 API. Returns OFFLINE clients only — currently connected clients are excluded, so merge with unifi_list_clients for a full inventory. Includes names, MACs, first_seen and last_seen epoch seconds when available. This is inventory, not session history; use unifi_list_client_sessions for past connections. Requires controller history API-key support; errors never mean zero activity. Retention depends on the controller. Returns the most recently seen clients first, up to limit, with totalCount; truncated: true means less recently seen clients were left out, so raise limit (narrowing withinHours drops those same clients). Rows carry only mac, hostname, display_name, first_seen, last_seen, is_wired, status.

Input Schema

Name	Required	Description
`limit`	No	Maximum clients, most recently seen first
`withinHours`	No	Lookback in hours, up to one year; does not extend controller retention
`siteReference`	Yes	Site internalReference from unifi_list_sites (often default), not the Integration API UUID

Output Schema

Name	Required	Description	Default
`data`	Yes
`count`	Yes
`limit`	Yes
`coverage`	Yes
`truncated`	Yes
`totalCount`	Yes
`withinHours`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv2.15.0Oct 14, 2026

addedInput schema / properties / limit

Added value: +{
+  "default": 100,
+  "description": "Maximum clients, most recently seen first",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +{}
```
addedOutput schema / properties / limit
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / totalCount
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / truncated
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "data",
-  "count",
-  "withinHours",
-  "coverage"
-]New value: +[
+  "data",
+  "count",
+  "totalCount",
+  "limit",
+  "truncated",
+  "withinHours",
+  "coverage"
+]

Addedv2.14.0Sep 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), and the description goes well beyond them: API-key dependency, error semantics, controller-dependent retention, result ordering, totalCount and truncated behavior, and the limit-vs-withinHours trade-off. These are exactly the traits an agent needs and none are in 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.

Conciseness4/5

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

Dense but front-loaded: purpose, expclusions, and sibling routing come first, then operational caveats. The final sentence enumerating row fields ('mac, hostname, display_name...') partially duplicates the output schema, which is minor waste, but the rest of the text is high-value.

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 filtered list tool with an output schema already present, the description covers everything else an agent needs: scope, exclusions, ordering, truncation, error interpretation, retention limits, and API-key prerequisites. Nothing consequential is missing.

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 baseline is 3, but the description adds genuinely useful semantics the schema lacks: result ordering is 'most recently seen first up to limit', and narrowing withinHours drops the same clients excluded by truncation. That interaction between limit/truncated/withinHours is real added value over the per-parameter 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?

States a specific verb+resource ('List historical/offline client inventory') and immediately scopes it: 'Returns OFFLINE clients only — currently connected clients are excluded.' It names the two siblings that could be confused with it, unifi_list_clients and unifi_list_client_sessions, so an agent can route correctly without opening any schema.

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?

Explicit when-to-use and when-not-to-use guidance: merge with unifi_list_clients for a full inventory, and use unifi_list_client_sessions for past connections rather than this tool. It also states the precondition ('requires controller history API-key support') and the failure interpretation ('errors never mean zero activity').

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

Deploy Server