arr-mcp

Overview Schema Source Related Servers Discussions Admin

Playback activity

get_playback

Read-only

Reads a media-server user's watch state: now playing and resumable items with position, the next unwatched episode of each series in progress, or recent play history, newest first.

Instructions

What a media-server user is watching, has next, or has watched; watch state exists only on the media server. scope: "active" (default): now playing and resumable, with position. "next_up": the next unwatched episode of each series in progress. "history": recent plays, newest first; on Jellyfin it includes plays from its activity log that were never marked played (an offline client syncing back), tagged source: "activity_log", as far back as Jellyfin keeps the log (30 days by default). Defaults to the configured user; another needs allow_other_users. With no media server configured every scope is empty and note says why: report that rather than saying nothing is playing. Field reference: arr://docs/get_playback.

Input Schema

Name	Required	Description	Default
`user`	No	Whose playback to read. Defaults to the configured default_user; any other value requires allow_other_users.
`limit`	No	Maximum items to return. Defaults to 50, hard maximum 500.
`scope`	No	`active` (default): now playing and what can be resumed. `next_up`: the next unwatched episode of every series this user has in progress — your media server's own answer to what to watch next. `history`: recently watched movies and episodes, newest first — on Jellyfin including plays its activity log holds that never got marked played, such as an offline client syncing back.	active
`detail`	No	How much per-item detail to return. Defaults to standard.	standard
`offset`	No	Items to skip: page two of 50 is `offset: 50`. Pair it with `sort`, or items can move between pages.

Output Schema

Name	Required	Description	Default
`note`	No
`items`	Yes
`total`	Yes
`counts`	No
`offset`	Yes
`degraded`	Yes
`returned`	Yes
`truncated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedv1.74.0Nov 9, 2026

removedInput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / offset / description

Previous value: -"How many items to skip before the window `limit` returns — page two of 50 is `offset: 50`. `total` always counts the whole list, so `offset + returned < total` is how you know there is another page. Pair it with `sort` for a stable walk: without one the order is whatever the services returned, and an item can move between pages."New value: +"Items to skip: page two of 50 is `offset: 50`. Pair it with `sort`, or items can move between pages."

removedInput schema / properties / offset / maximum
```
Removed value: -9007199254740991
```

removedOutput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

removedOutput schema / properties / counts / description

Removed value: -"How many results each service contributed."

removedOutput schema / properties / degraded / description

Removed value: -"Services that could not be reached. Their contribution is missing from `items`, so a short list may be an outage rather than an answer."

removedOutput schema / properties / items / description

Removed value: -"The window of results. What an item carries depends on the tool and on `detail`."

removedOutput schema / properties / note / description

Removed value: -"Present when a fact about the stack's config, not this call, needs stating — for example no media server configured at all."

removedOutput schema / properties / offset / description

Removed value: -"How many were skipped. `offset + returned < total` means there is another page."

removedOutput schema / properties / offset / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / properties / offset / minimum
```
Removed value: --9007199254740991
```
removedOutput schema / properties / returned / description
```
Removed value: -"How many are in `items`."
```
removedOutput schema / properties / returned / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / properties / returned / minimum
```
Removed value: --9007199254740991
```

removedOutput schema / properties / total / description

Removed value: -"How many matched in total — the whole list, never the window. Compare against `returned` before reporting a count to anyone."

removedOutput schema / properties / total / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / properties / total / minimum
```
Removed value: --9007199254740991
```

removedOutput schema / properties / truncated / description

Removed value: -"True when this is not the whole list — including on the last page of a paged walk, where the rest is behind you rather than ahead."

First observedv0.1.0Nov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses the Jellyfin-specific behaviour of pulling plays from the activity log that were never marked played, the `source: "activity_log"` tag, a 30-day default log retention, the allow_other_users authorization requirement for reading another user, and the empty-plus-note behaviour when no server is configured. These are exactly the non-obvious traits an agent needs to interpret results correctly.

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?

Front-loaded with the core purpose, then scope enumeration, then auth and empty-state caveats, then a docs pointer — a sensible information order. It is dense, and the Jellyfin activity-log caveat is repeated in both description and schema, but no sentence is wasted filler.

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?

With a rich 5-parameter schema, 100% description coverage, and an output schema covering return fields, the description fills the remaining gaps: default-user behavior, permission gate, empty-state semantics, and the Jellyfin log caveat. Nothing an agent needs to call it or interpret an empty response 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% and already documents all five parameters, so the baseline is 3; the description nudges above it by framing what each scope semantically means for the user (resumable position, 'your media server's own answer to what to watch next') and by pointing to a field reference for return shapes. The `user` and allow_other_users detail largely restates the schema.

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 opening clause states a specific resource and the three things it can return (watching, next, watched), and the note that 'watch state exists only on the media server' distinguishes it from library/metadata siblings like get_library or get_media_details. An agent can tell what this tool answers without opening the schema.

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?

Each scope is given an explicit condition for selection (now playing vs next unwatched episode per in-progress series vs recent plays), plus a concrete handling instruction for the empty-result case when no media server is configured. It stops short of naming sibling alternatives such as get_history, leaving the read-history vs playback-history boundary implicit.

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