Skip to main content
Glama
Plex MCP Server

Plex MCP Server

by dustinhansen

List media

list_media
Read-onlyIdempotent

List and filter movies, shows, episodes, artists, albums, tracks, or collections by watched state, rating, genre, year, and more, returning view counts and last-viewed data.

Instructions

List items from any library with rich filtering. Returns watched state, view counts and last-viewed on every record. watched defaults to 'all': the full library, seen and unseen. For SHOW libraries: the watched filter means any-episode-played (watched) / has-unplayed-episodes (unwatched), while each record's watched field means fully watched. A partially-watched show matches both filters' opposites. kind defaults to the kind a named collection holds, else the library's natural top-level type (movie/show/artist). Use episode/track/album/season for deeper types, or collection to list a section's collections. rated filters on the owner's star rating (userRating, 1-10 internal scale). Movie records carry userRating, and sort=userRating asc puts unrated first. Filters combine (AND). Paginate with offset/limit. detail=true caps limit at 25 and adds fields such as directors, actors, collections and summaries. The result's filters object names what each genre/collection/country/studio/label filter matched: the same name ignoring case first, else the first one containing it. kind=collection lists a section's collections only. Other filters/sort are ignored for collections.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_media"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNo
sortNoaddedAt
userNosee the library as this Plex Home user (name or id)
yearNo
genreNo
labelNofilter to items carrying this Plex label. Plex lists every label on the server under every library, so a label used only in another library returns no items rather than an error
limitNo
orderNodesc
ratedNoall
decadeNoe.g. '1970s'
detailNo
fieldsNoproject each record to these keys (ratingKey always kept). Use to keep large listings small
offsetNo
studioNo
countryNo
libraryNoMovies
watchedNoall
addedSinceNoISO date or relative like '-30d'
collectionNofilter to members of a collection. Leaving kind out uses the kind of item the collection holds. A smart collection with no tag is an error naming the ratingKey to pass to get_children
contentRatingNoe.g. 'PG-13'
maxDurationMinNo
lastViewedAfterNolast viewed after this ISO date or relative like '-30d'
lastViewedBeforeNolast viewed before this ISO date or relative like '-3y'. Never-watched items match too unless watched='watched'

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.10.0
    • changedInput schema / properties / collection / description
      Previous value: -"filter to members of a collection"New value: +"filter to members of a collection. Leaving kind out uses the kind of item the collection holds. A smart collection with no tag is an error naming the ratingKey to pass to get_children"
    • addedInput schema / properties / label
      Added value: +{
      +  "description": "filter to items carrying this Plex label. Plex lists every label on the server under every library, so a label used only in another library returns no items rather than an error",
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. First observedv0.9.0

TDQS

A4.2/5.0
Behavior5/5

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

Goes well beyond the read-only/idempotent annotations by disclosing non-obvious semantics: every record returns watched state, view counts and last-viewed; for shows the watched filter means any-episode-played while the record field means fully watched; a partially-watched show matches both filter opposites. It also warns that detail=true caps limit at 25, that filters combine with AND, that the result's filters object reports case-insensitive-then-substring matching, and that smart collections without a tag error out with a ratingKey hint.

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 then organized roughly by concern: return fields, watched semantics, kind resolution, rated/sort, filter combination, pagination/detail, and the filters echo object. It is dense and delivered as a single unbroken block, so an agent must read the whole thing to find the collection caveat that sits at the very end, but nearly every clause carries unique information.

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

Completeness4/5

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

For a 23-parameter, zero-required listing tool with no output schema, the description supplies the pieces an agent most needs: what records contain, how the watched filter differs from the watched field, how kind is resolved, pagination via offset/limit, detail's limit cap, and how the response self-documents filter matching. The residual gaps are the unexplained minor filter parameters, but none are likely to cause a wrong call.

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?

With only 39% schema description coverage across 23 parameters, the description carries real weight, and it does so for the ambiguous ones: watched, kind, rated (owner's 1-10 userRating scale, unrated-first on ascending sort), collection, detail, and the limit cap. It leaves many parameters (user, genre, decade, fields, lastViewedAfter/Before, maxDurationMin) undocumented beyond their names or short schema text, so some meaning is still missing.

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

Purpose4/5

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

Opens with a specific verb and resource: 'List items from any library with rich filtering,' which tells an agent exactly what the tool produces. It does not, however, differentiate itself from siblings like search, get_children, or list_libraries, so an agent still has to infer when this is the right listing tool versus a search or a child fetch.

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?

Gives strong conditional guidance inside the tool: kind defaults to the collection's held kind or the library's natural top-level type, deeper types are reached via episode/track/album/season, and collection lists a section's collections (with other filters ignored). What it lacks is explicit tool-level routing, such as 'use search when you have a title fragment' or 'use get_children to descend into a collection,' so the agent gets clear context but no named alternatives or exclusions.

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