mcp-plex
Provides tools for interacting with a Plex Media Server, enabling media discovery, search, library browsing, collection and playlist management, watch state control, and library scanning.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-plex search for interstellar"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Python 3.14+
A running Plex Media Server
A Plex authentication token
Related MCP server: plex-mcp
Setup
1. Get Your Plex Token
The easiest way to find your Plex token:
Sign in to Plex Web App
Browse to any media item and click Get Info (or ... > Get Info)
Click View XML in the bottom-left
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 sync3. 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-serverThe 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 across all libraries. Optional type filter: "movie", "show", "episode", "artist", "album", "track". |
|
| Recently added media, optionally filtered to a library. |
|
| Continue watching / next episode list. |
Library Browsing
Tool | Parameters | Description |
| (none) | List all library sections with types and item counts. |
|
| Browse a library. Sort by title, date added, year, or rating. |
|
| Full details for one item: summary, genres, cast, directors, ratings. |
|
| Item counts and stats for one or all libraries. |
Shows
Tool | Parameters | Description |
|
| List seasons for a TV show. |
|
| List episodes (all or by season). |
Collections
Tool | Parameters | Description |
|
| List collections in a library (includes smart/regular type). |
|
| Get collection details and all items it contains. |
|
| Create a regular collection from specific items. |
|
| Create a smart (filter-based) auto-updating collection. |
|
| Edit collection metadata (title, summary, sort, display mode). |
|
| Add items to a regular collection. |
|
| Remove items from a regular collection. |
|
| Delete a collection (does not affect the media items). |
Playlists
Tool | Parameters | Description |
| (none) | List all playlists on the server. |
|
| Get items in a playlist. |
Watch State
Tool | Parameters | Description |
|
| Mark a movie, episode, or track as fully watched. |
|
| Mark an item as unwatched, resetting progress. |
|
| Remove a movie or episode from Continue Watching / On Deck. |
|
| Set playback position in milliseconds (must be > 0). |
Management
Tool | Parameters | Description |
|
| 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 checkPre-commit Hooks
This project uses lefthook for pre-commit checks. Install with brew install lefthook (or see other install methods), then:
lefthook installAvailable Tools
25 toolsadd_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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
The official MCP Server for the Mux API
The official Planning Center MCP server for interacting with your ministry's data.
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
Related MCP Servers
- FlicenseAqualityDmaintenanceA Python-based MCP server that integrates with Plex Media Server API to search for movies and manage playlists in your Plex media library.97-
- AlicenseNot gradedqualityBmaintenanceLets MCP clients browse and search your Plex media libraries.1MIT
- AlicenseAqualityCmaintenanceMCP server for managing a media server stack (Plex, Radarr, Overseerr, Bazarr, Prowlarr, Trakt.tv) using natural language to browse, request, and discover content.12MIT
- AlicenseAqualityBmaintenanceAn 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.222MIT