Skip to main content
Glama

mcp-plex

MCP server for Plex Media Server, focused on media discovery, search, library management, and playback control. 24 granular tools designed for use with Claude and other LLM agents.

Prerequisites

Related MCP server: plex-mcp

Setup

1. Get Your Plex Token

The easiest way to find your Plex token:

  1. Sign in to Plex Web App

  2. Browse to any media item and click Get Info (or ... > Get Info)

  3. Click View XML in the bottom-left

  4. In the URL bar, find the X-Plex-Token= parameter -- that's your token

Alternatively, check the Plex support article for other methods.

2. Install

cd mcp-plex
uv sync

3. Configure Environment Variables

Set these before running the server:

export PLEX_SERVER_URL="http://your-plex-server:32400"
export PLEX_TOKEN="your_plex_token"

4. Test the Connection

uv run mcp-plex-server

The server connects to your Plex server on startup and verifies the token. If the connection fails, check that your server URL and token are correct.

Claude Desktop / Claude Code Configuration

Add to your MCP server config. If installed from PyPI:

{
  "mcpServers": {
    "plex": {
      "command": "uvx",
      "args": ["mcp-plex-server"],
      "env": {
        "PLEX_SERVER_URL": "http://your-plex-server:32400",
        "PLEX_TOKEN": "your_plex_token"
      }
    }
  }
}

Or if running from a local clone:

{
  "mcpServers": {
    "plex": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-plex", "run", "mcp-plex-server"],
      "env": {
        "PLEX_SERVER_URL": "http://your-plex-server:32400",
        "PLEX_TOKEN": "your_plex_token"
      }
    }
  }
}

Tools

Discovery

Tool

Parameters

Description

search_media

query, media_type="", limit=20

Search across all libraries. Optional type filter: "movie", "show", "episode", "artist", "album", "track".

get_recently_added

limit=20, library_name=""

Recently added media, optionally filtered to a library.

get_on_deck

limit=10

Continue watching / next episode list.

Library Browsing

Tool

Parameters

Description

get_libraries

(none)

List all library sections with types and item counts.

get_library_contents

library_name, sort="titleSort", limit=50

Browse a library. Sort by title, date added, year, or rating.

get_media_details

rating_key

Full details for one item: summary, genres, cast, directors, ratings.

get_library_stats

library_name=""

Item counts and stats for one or all libraries.

Shows

Tool

Parameters

Description

get_seasons

rating_key

List seasons for a TV show.

get_episodes

rating_key, season_number=0

List episodes (all or by season).

Collections

Tool

Parameters

Description

get_collections

library_name

List collections in a library (includes smart/regular type).

get_collection_items

rating_key

Get collection details and all items it contains.

create_collection

library_name, title, rating_keys

Create a regular collection from specific items.

create_smart_collection

library_name, title, filters, libtype="", sort="", limit=0

Create a smart (filter-based) auto-updating collection.

edit_collection

rating_key, title="", summary=None, sort_order="", mode=""

Edit collection metadata (title, summary, sort, display mode).

add_to_collection

rating_key, item_rating_keys

Add items to a regular collection.

remove_from_collection

rating_key, item_rating_keys

Remove items from a regular collection.

delete_collection

rating_key

Delete a collection (does not affect the media items).

Playlists

Tool

Parameters

Description

get_playlists

(none)

List all playlists on the server.

get_playlist_items

rating_key

Get items in a playlist.

Watch State

Tool

Parameters

Description

mark_watched

rating_key

Mark a movie, episode, or track as fully watched.

mark_unwatched

rating_key

Mark an item as unwatched, resetting progress.

remove_from_continue_watching

rating_key

Remove a movie or episode from Continue Watching / On Deck.

set_playback_progress

rating_key, progress_ms

Set playback position in milliseconds (must be > 0).

Management

Tool

Parameters

Description

scan_library

library_name

Trigger a background library scan.

Development

uv run mcp-plex-server              # Run the server
uv run ruff check src/       # Lint
uv run ruff format src/      # Format
uv run pyright src/          # Type check

Pre-commit Hooks

This project uses lefthook for pre-commit checks. Install with brew install lefthook (or see other install methods), then:

lefthook install

Available Tools

25 tools
add_to_collectionA

Add items to a regular (non-smart) collection.

rating_key: the collection's rating key. item_rating_keys: list of rating keys for items to add.

Inputs: rating_key (required), item_rating_keys (required).

create_collectionA

Create a new regular collection in a Plex library.

library_name: exact library name (e.g. "Movies"). title: name for the collection. rating_keys: list of rating keys for items to include.

Inputs: library_name (required), title (required), rating_keys (required).

create_smart_collectionA

Create a smart (filter-based) collection that auto-updates.

library_name: exact library name (e.g. "Movies"). title: name for the collection. filters: dict of field/value pairs with optional operators. Operators are appended to the key: ">>" = greater than, "<<" = less than, "!" = not. Examples: {"genre": "Action"} -- genre is Action {"year>>": 2000} -- year greater than 2000 {"genre!": "Horror"} -- genre is not Horror {"genre": "Action", "year>>": 2000} -- both conditions Common fields: genre, year, decade, rating, audienceRating, contentRating, resolution, studio, label, director, actor. libtype: content type to filter (required for show libraries). "movie", "show", "episode", "season", "artist", "album", "track". sort: sort order (e.g. "titleSort", "year:desc", "rating:desc"). limit: max items (0 = unlimited).

Inputs: library_name (required), title (required), filters (required), libtype, +2 more.

delete_collectionB

Delete a collection from the Plex library.

This permanently removes the collection. The media items themselves are not affected.

Inputs: rating_key (required). Returns: result

edit_collectionB

Edit a collection's metadata.

rating_key: the collection's rating key. title: new title (empty = no change). summary: new summary (None = no change, empty string = clear). sort_order: "release", "alpha", or "custom" (empty = no change). mode: "default", "hide", "hideItems", or "showItems" (empty = no change).

Inputs: rating_key (required), title, summary, sort_order, +1 more.

get_collection_itemsB

Get the items in a Plex collection with full collection details.

Provide the rating_key of a collection. Returns collection metadata (title, smart, mode, sort, labels) and the media items it contains.

Inputs: rating_key (required).

get_collectionsA

List collections in a Plex library.

Returns collection names, types (smart/regular), item counts, and rating keys. Use get_collection_items to see the contents.

Inputs: library_name (required). Returns: result

get_episodesA

Get episodes for a TV show or season.

Provide the rating_key of a show. Optionally filter by season_number (0 = all seasons). Returns episode titles, numbers, and durations.

Inputs: rating_key (required), season_number. Returns: result

get_librariesA

List all library sections on the Plex server.

Returns library names, types (movie, show, artist), item counts, and last updated timestamps.

Inputs: no named parameters. Returns: result

get_library_contentsA

Browse the contents of a specific Plex library.

library_name must match exactly (e.g. "Movies", "TV Shows"). Use get_libraries to see available names.

Sort options: "titleSort" (default), "addedAt:desc", "year:desc", "rating:desc", "audienceRating:desc".

Inputs: library_name (required), sort, limit. Returns: result

get_library_statsA

Get statistics for Plex libraries.

Without library_name: returns item counts for all libraries. With library_name: returns detailed stats for that library.

Inputs: library_name. Returns: result

get_media_detailsA

Get detailed information about a specific media item.

Use the rating_key from search or browse results. Returns full details including summary, genres, cast, directors, and ratings.

Inputs: rating_key (required).

get_on_deckB

Get the "On Deck" continue-watching list from Plex.

Returns items that are partially watched or next episodes in a series.

Inputs: limit. Returns: result

get_playlist_itemsC

Get the items in a Plex playlist.

Provide the rating_key of a playlist. Returns the media items contained in the playlist.

Inputs: rating_key (required). Returns: result

get_playlistsA

List all playlists on the Plex server.

Returns playlist names, types, item counts, and durations.

Inputs: no named parameters. Returns: result

get_recently_addedC

Get recently added media from Plex.

Returns the most recently added items across all libraries, or filtered to a specific library by name (e.g. "Movies", "TV Shows").

Inputs: limit, library_name. Returns: result

get_seasonsA

Get the seasons of a TV show.

Provide the rating_key of a show (from search or browse). Returns season numbers, episode counts, and rating keys.

Inputs: rating_key (required). Returns: result

get_server_versionA

Return the installed version of the mcp-plex-server package.

Inputs: no named parameters. Returns: result

mark_unwatchedC

Mark a media item as unwatched, resetting its watch progress.

Works on movies, episodes, and tracks.

Inputs: rating_key (required). Returns: result

mark_watchedB

Mark a media item as fully watched.

Works on movies, episodes, and tracks.

Inputs: rating_key (required). Returns: result

remove_from_collectionA

Remove items from a regular (non-smart) collection.

rating_key: the collection's rating key. item_rating_keys: list of rating keys for items to remove.

Inputs: rating_key (required), item_rating_keys (required).

remove_from_continue_watchingA

Remove a partially-watched item from the Continue Watching / On Deck list.

Only works on movies and episodes. Does not change the item's watched/unwatched state.

Inputs: rating_key (required). Returns: result

scan_libraryB

Trigger a library scan on the Plex server.

This refreshes the library to pick up new or changed media files. The scan runs in the background on the server.

Inputs: library_name (required). Returns: result

search_mediaA

Search for media across all Plex libraries.

Searches movies, shows, music, and other media by title.

Optional media_type filter: "movie", "show", "episode", "artist", "album", "track".

Returns titles, years, ratings, and rating keys for further lookup.

Inputs: query (required), media_type, limit. Returns: result

set_playback_progressA

Set the playback progress for a media item to a specific position.

rating_key: the item's rating key. progress_ms: position in milliseconds (must be > 0). To reset progress to zero, use mark_unwatched instead.

Inputs: rating_key (required), progress_ms (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 25 tools

    Disambiguation5/5

    Each tool targets a distinct action (e.g., collection operations, playlist retrieval, library browsing, watch status) with no functional overlap. Even similar operations like add_to_collection vs create_collection are clearly separated.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., create_collection, get_libraries, mark_watched). No mixed conventions or vague verbs.

    Tool Count4/5

    25 tools is slightly above the typical 3-15 range, but each tool serves a specific purpose in media management (collections, playlists, libraries, episodes, progress). The count is justified given the breadth of operations, though a few could be merged.

    Completeness3/5

    The tool surface covers core workflows like collections, libraries, search, and watch status. However, notable gaps exist: no create_playlist or delete_playlist, and no tool to update media metadata (e.g., edit title/summary of a movie). These are common Plex operations.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a media server stack (Plex, Radarr, Overseerr, Bazarr, Prowlarr, Trakt.tv) using natural language to browse, request, and discover content.
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server for Plex Media Server that enables natural language interaction with your media library, including search, browse, and chat features via an optional web app.
      22
      2
      MIT