arr-mcp

Overview Schema Source Related Servers Discussions Admin

Library

get_library

Read-only

Query a unified media library across Radarr, Sonarr, Whisparr, Lidarr, Grimmory, and your media server, with filters, sorting, counts, and presence checks to spot broken imports or unmanaged titles.

Instructions

Your library joined across Radarr, Sonarr, Whisparr, Lidarr, Grimmory and your media server on shared external ids: films, series, artists and books. Use it for filtered lists and counts; for one title use get_media_details. presence is what no single service can tell: arr_only with a file is a likely broken import, jellyfin_only (spelled that way for any media server) is media nothing manages, and unknown means the other half was not read. When degraded or note explain a gap, report that reason rather than calling it unwatched or unrated. has_file: false with monitored: true is what you are still waiting for. An artist's monitored is the artist-level flag, not the album flag; its albums and their ids come from get_media_details on the Lidarr artist. A series has an IMDb rating only with the IMDb dataset on, so ask rating_source: "imdb" explicitly. Series seasons and folder paths need detail: "full". Field reference: arr://docs/get_library.

Input Schema

Name	Required	Description	Default
`kind`	No	Films, series, Lidarr artists or Grimmory books. Omit for all.
`sort`	No	Order the results before `limit` is applied — which is what makes "the best rated" or "most recently added" answerable at all, since a filter alone would leave the top item outside the returned window. `rating` is descending and uses `rating_source`, excluding items that source has no rating for and reporting them in `ratingCoverage`; `added` is newest first and excludes media no *arr manages, which has no added date; `year` is descending; `title` ascending. Omit to keep the library's own order.
`user`	No	Whose playback to read. Defaults to the configured default_user; any other value requires allow_other_users.
`year`	No
`genre`	No	Matched case-insensitively against the *arr genres.
`limit`	No	Maximum items to return. Defaults to 50, hard maximum 500.
`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.
`library`	No	A Grimmory library, by name. Matches books only.
`quality`	No	Films, or a book's file format such as EPUB.
`watched`	No	The media server's watch state, or a Grimmory book's read status (READ is watched). Items it has never seen count as unwatched. Pair with `user` to ask about someone else.
`has_file`	No	Whether a file is actually on disk. For an artist this means any track of any of its albums is on disk. `false` with `monitored: true` is "what am I still waiting for"; `true` is "what can I watch now". Media no *arr manages is excluded from both answers rather than counted as missing — nothing is going to fetch it.
`presence`	No	both / arr_only (possible broken import) / jellyfin_only (unmanaged media — the value keeps this name whichever media server is configured) / unknown (media server degraded or unconfigured, so arr_only cannot be asserted; for an artist it also means the music read did not run).
`monitored`	No
`min_rating`	No	Always 0-10, regardless of source. Metacritic and Rotten Tomatoes are reported in the response on their native 0-100 scale, but rescaled to 0-10 for this comparison.
`watched_by`	No	Whose playback to read. Defaults to the configured default_user; any other value requires allow_other_users.
`added_since`	No	Only items added at or after this ISO 8601 date. Items with no added date are left out.
`rating_source`	No	Defaults to whichever source covers the most of your library. `tvdb` is series-only.

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.

Changed20 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
```
removedInput schema / properties / year / maximum
```
Removed value: -9007199254740991
```
removedInput schema / properties / year / minimum
```
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 — no media server configured at all, or one configured with no default_user."

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.8/5.0

Behavior5/5

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

With readOnlyHint already declaring the safety profile, the description goes well beyond it: it explains what each `presence` value means operationally (arr_only + file = likely broken import; jellyfin_only = unmanaged media; unknown = other half not read), instructs the agent to report `degraded`/`note` reasons instead of mislabelling items unwatched, and warns that an artist's `monitored` is the artist-level flag, not the album flag.

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 purpose and the sibling hand-off before the caveats, and almost every sentence carries non-obvious information. It is dense and backtick-heavy, with a few clauses that restate schema points, but no padding of the kind that would obscure the main routing signal.

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 an 18-parameter read tool with an output schema, the description covers exactly what the schema cannot: cross-service join semantics, degraded-read handling, monitored-flag ambiguity, and the detail/rating-source prerequisites. It also points to arr://docs/get_library for the full field reference, so remaining gaps are addressable.

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 89%, so the baseline is 3, but the description adds real meaning on top: it clarifies that `presence`'s jellyfin naming is fixed regardless of configured server, that `rating_source` defaults to the widest-coverage source and that IMDb series ratings require the dataset, and that `detail: "full"` is a prerequisite for seasons and folder paths. It adds less for the plain filter params, which the schema already documents well.

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 first sentence names the specific resource (a cross-service library union over Radarr/Sonarr/Whisparr/Lidarr/Grimmory plus the media server), the join key (shared external ids) and the entity types covered. It also explicitly contrasts with get_media_details for single-title lookups, so an agent can route without opening either 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 division of labour: 'Use it for filtered lists and counts; for one title use get_media_details.' Beyond that it gives task-level guidance for the hard cases — 'has_file: false with monitored: true is what you are still waiting for', and when to ask for `rating_source: "imdb"` or `detail: "full"`.

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