Plex MCP Server

List media

list_media

Read-onlyIdempotent

Browse and filter Plex library items by type, genre, year, rating, and watch status, returning view counts and last-viewed data with pagination.

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 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. kind=collection lists a section's collections only. Other filters/sort are ignored for collections.

Input Schema

Name	Required	Description	Default
`kind`	No
`sort`	No		addedAt
`user`	No	see the library as this Plex Home user (name or id)
`year`	No
`genre`	No
`limit`	No
`order`	No		desc
`rated`	No		all
`decade`	No	e.g. '1970s'
`detail`	No
`fields`	No	project each record to these keys (ratingKey always kept). Use to keep large listings small
`offset`	No
`studio`	No
`country`	No
`library`	No		Movies
`watched`	No		all
`addedSince`	No	ISO date or relative like '-30d'
`collection`	No	filter to members of a collection
`contentRating`	No	e.g. 'PG-13'
`maxDurationMin`	No
`lastViewedAfter`	No	last viewed after this ISO date or relative like '-30d'
`lastViewedBefore`	No	last 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.

First observedv0.9.0Oct 29, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations already declare a safe read-only, idempotent profile, and the description still adds substantial non-obvious behavior: the watched filter means any-episode-played for shows while the record's watched field means fully watched, partially-watched items match both opposites, detail=true caps limit at 25, filters combine with AND, and kind=collection ignores other filters/sort. These are exactly the semantics an agent could get wrong.

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 and long, but appropriate for a 22-parameter tool, and key defaults (watched='all', kind default) are front-loaded. Some sentences, especially the repeated mention of kind=collection, could be consolidated without losing meaning.

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 high-complexity listing tool with no output schema, the description does note what records carry (watched state, view counts, last-viewed) and warns about the detail cap. Pagination is mentioned via offset/limit. Coverage of the many remaining filters is the only real gap.

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 36% schema coverage over 22 params, the description carries much of the weight, correctly defining watched, rated (internal 1-10 scale), sort=userRating putting unrated first, the detail limit cap, and collection-only mode. It leaves several filters (year, genre, decade, studio, country, maxDurationMin) unexplained beyond their names, so it is strong but not complete.

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?

Opening sentence gives a specific verb and resource ('List items from any library') plus the scope of functionality ('rich filtering'). It is clearly distinct from siblings like library_stats or get_item, though it never names those alternatives to sharpen the boundary.

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

Usage Guidelines3/5

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

The description explains how to use the filters (kind defaults, deep types via episode/track/album/season, collection for sections) but never states when to choose this over search, library_stats, or get_children. Usage is implied by the filter guidance rather than framed against alternatives.

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

List media

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools