Skip to main content
Glama
HoneyBearTech

plex-director-mcp

by HoneyBearTech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

search_plex_library

Find movies and TV shows in your Plex libraries by genre, actor, title, year, or library. Combine filters to see what you own or can watch.

Instructions

Searches the movies and TV shows actually in the user's Plex library (across all movie and show libraries, including 4K) by genre, actor, title, release year, and/or library. Filters can be combined, e.g. genre 'Horror' with year 1982, or genre 'Horror' with library '4k'. Pass mediaType 'movie' when the user asks about movies/films, 'show' for TV/series/shows, and leave it out (any) when the question is about titles in general, e.g. everything with an actor; a show in several libraries is one result, with its season and episode counts. Some libraries (such as Sports) may be left out unless named in the library filter. Use this to answer what the user owns or can watch; use check_movie_status for Radarr/download status of one specific movie. Watch state: use watched 'unwatched' (never played), 'inProgress' (started but not finished - this is the complete list of unfinished titles, unlike get_on_deck's short recent list) or 'watched' (finished), and notWatchedInYears for 'haven't watched in N years' (a never-watched title counts from when it was added); they are for the Plex account the app is connected with. sort orders by recentlyAdded, lastWatched or leastRecentlyWatched instead of by title. Also filter by network (or movie studio), contentRating (TV-MA, R...), minRating (audience rating 0-10), yearFrom/yearTo (a decade is 1990 to 1999) and addedWithinDays ('what showed up this week?'). Plex does not know whether a show is continuing or ended; use Sonarr tools for that. Always express a narrowing the user asks for (4K, a genre, a year, unwatched...) as a filter here rather than filtering results yourself, because the results table shown to the user contains exactly the rows this returns. The default limit is small: when the user wants everything ('all', 'every', 'list them'), pass limit 500; if the reply says more matches remain, call again with the offset it gives.

Input Schema

NameRequiredDescriptionDefault
sortNoOrder the results (default title).
yearNoRelease year (a show's first air year).
actorNoFull actor name, e.g. 'Harrison Ford'.
genreNoGenre name, e.g. 'Horror' or 'Science Fiction'.
limitNoMaximum results to return (default 25, max 500).
titleNoPart of the movie or show title.
offsetNoMatches to skip, to fetch the next page of a long result.
yearToNoReleased in or before this year.
libraryNoOnly search Plex libraries whose name contains this text, e.g. '4k' for the 4K libraries, 'kids', 'anime', 'sports'.
networkNoTV network (shows) or studio (movies), e.g. 'HBO', 'Netflix'.
watchedNoOnly titles never played, started but not finished, or finished.
yearFromNoReleased in or after this year (a decade: 1990 to 1999).
mediaTypeNoSearch only movies, only TV shows, or both (default any).
minRatingNoAudience rating of at least this (0-10).
contentRatingNoContent rating, e.g. 'TV-MA', 'PG-13', 'R'.
addedWithinDaysNoAdded to Plex within this many days.
notWatchedInYearsNoOnly titles not watched for this many years (a never-watched title counts from when it was added).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changedv1.2.0
    • addedInput schema / properties / addedWithinDays
      Added value: +{
+  "description": "Added to Plex within this many days.",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}
    • addedInput schema / properties / contentRating
      Added value: +{
+  "description": "Content rating, e.g. 'TV-MA', 'PG-13', 'R'.",
+  "type": "string"
+}
    • changedInput schema / properties / library / description
      Previous value: -"Only search Plex libraries whose name contains this text, e.g. '4k' for the 4K libraries, 'kids', 'documentaries'."New value: +"Only search Plex libraries whose name contains this text, e.g. '4k' for the 4K libraries, 'kids', 'anime', 'sports'."
    • addedInput schema / properties / mediaType
      Added value: +{
+  "description": "Search only movies, only TV shows, or both (default any).",
+  "enum": [
+    "movie",
+    "show",
+    "any"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / minRating
      Added value: +{
+  "description": "Audience rating of at least this (0-10).",
+  "maximum": 10,
+  "minimum": 0,
+  "type": "number"
+}
    • addedInput schema / properties / network
      Added value: +{
+  "description": "TV network (shows) or studio (movies), e.g. 'HBO', 'Netflix'.",
+  "type": "string"
+}
    • addedInput schema / properties / notWatchedInYears
      Added value: +{
+  "description": "Only titles not watched for this many years (a never-watched title counts from when it was added).",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}
    • addedInput schema / properties / sort
      Added value: +{
+  "description": "Order the results (default title).",
+  "enum": [
+    "title",
+    "recentlyAdded",
+    "lastWatched",
+    "leastRecentlyWatched"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / title / description
      Previous value: -"Part of the movie title."New value: +"Part of the movie or show title."
    • addedInput schema / properties / watched
      Added value: +{
+  "description": "Only titles never played, started but not finished, or finished.",
+  "enum": [
+    "unwatched",
+    "inProgress",
+    "watched"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / year / description
      Previous value: -"Release year."New value: +"Release year (a show's first air year)."
    • addedInput schema / properties / yearFrom
      Added value: +{
+  "description": "Released in or after this year (a decade: 1990 to 1999).",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedInput schema / properties / yearTo
      Added value: +{
+  "description": "Released in or before this year.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
  2. Addedv1.1.0

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the default small limit, the pagination flow (offset, 'more matches remain'), that a show in multiple libraries is deduplicated into one result, that some libraries are excluded unless named, and that watch state maps to the connected Plex account. It omits auth/permission requirements and error behavior, so it stops short of a 5.

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 routing, then details; every part is dense with usable information. It is a single long block rather than a scannable structure and repeats several things already in the schema (network/contentRating/minRating examples, sort enum values, decade hint), which costs it the top score.

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 17-parameter tool with no output schema and no annotations, the description is unusually complete: it explains the shape of returned rows (one row per title, season/episode counts), the pagination contract, library inclusion quirks, and how filters combine. Nothing an agent needs to call it correctly appears to be 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 genuine meaning beyond the schema: how mediaType should be chosen from user phrasing, the semantic split of watched values, that notWatchedInYears counts never-watched titles from their add date, that a decade is expressed as yearFrom/yearTo, and that limit 500 should be passed for 'all/every' requests.

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 and resource ('Searches the movies and TV shows actually in the user's Plex library') and scopes it to owned content. It explicitly distinguishes itself from siblings: check_movie_status for Radarr/download status, Sonarr tools for continuing/ended status, and get_on_deck for recent unfinished items.

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?

Extensive when-to-use routing: mediaType mapping for movie/show/any queries, watched vs inProgress vs watched usage, when to use notWatchedInYears, and a direct instruction to express any narrowing as a filter here rather than post-filtering. It also names alternatives for adjacent queries.

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

Deploy Server

Other Tools