Plex MCP server
Summary: This server exposes Plex to Claude — all 405 Plex API operations (353 on your media server, 52 on plex.tv) behind 28 tools, with the rest reachable by search-and-run.
Libraries — list library sections, browse a section's items (filter by genre, studio, year, resolution, unwatched), get collections and a collection's items
Metadata — fetch items by rating key/IDs, children of an item, similar items, with optional refreshes and field/element includes
Discovery — global recently added, continue watching, hub search across Plex
Sessions & history — who is streaming now, playback history filtered by account, device, library or item
Playlists — list playlists, read contents, create one, add items to one
Watched state & ratings — mark items played/unplayed (scrobble), rate items
Watchlist — read your watchlist, add or remove items
Maintenance — refresh a library section (optionally one path), get server identity
Everything else —
find_operationsearches all 405 operations by words;run_operationruns any of them by name (including butler tasks, transcoder, DVR, Live TV, settings, plex.tv sharing/devices/account)Large answers —
get_result_pagepages, filters by field text, narrows fields and picks which list to walk; nothing is re-fetchedTwo hosts, auto-routed — media-server calls go to your server, watchlist/sharing/device/account calls go to plex.tv
Remote access — can be hosted over HTTP with OAuth 2.1 sign-in or a fixed bearer token as a Claude.ai custom connector
Provides comprehensive integration with Plex, exposing all 405 Plex API operations as tools, covering both local media server management (libraries, playlists, transcoder, hubs, settings, DVRs, live TV, etc.) and plex.tv cloud services (watchlist, sharing, devices, account).
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., "@Plex MCP server what's currently playing on my Plex?"
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.
Plex MCP server
Run Plex from Claude.ai, Claude Desktop and Claude Code. All 405 operations are reachable: 353 on your media server and 52 on the plex.tv cloud services, each routed to the right host automatically. 25 everyday ones are tools of their own; find_operation and run_operation reach the rest, so the tool list stays about 8 400 tokens.
Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. SeeDISCLAIMER.md.
Why not the other options
Measured against the community spec Plex's own SDKs are generated from, which has 344 paths and 405 operations:
Server | Plex tools | Coverage |
| ~40 | 10 % |
| libraries, playlists, clients | partial |
| viewing context and subtitles | partial |
This one | 405 | 100 % |
The existing servers cover libraries, playlists and what is playing. None of them reach the transcoder, the hub and discovery endpoints, butler tasks, server settings, sync, or the plex.tv side at all: watchlist, sharing, devices and account.
Related MCP server: Plex-MCP
How it stays complete
Plex publishes no OpenAPI document. LukeHagar/plex-api-spec is the community one Plex's own SDKs are generated from; scripts/convert_spec.py slims its 2.5 MB down to what the generator reads and records which host each operation belongs to:
curl -o plex-api-spec.yaml https://raw.githubusercontent.com/LukeHagar/plex-api-spec/main/plex-api-spec.yaml
python scripts/convert_spec.py plex-api-spec.yaml openapi.json
python scripts/generate_tools.py openapi.json src/plex_mcp/tools.pyA test compares every generated call against every operation in the spec, in both directions. An endpoint Plex adds and this misses fails the build; so does a tool pointing at an endpoint the spec does not define.
Tool names
Verb first, derived from the method and path, so the name says what it does:
Pattern | Meaning | Example |
| Read a collection |
|
| Read one record |
|
| POST |
|
| PUT |
|
| DELETE |
|
28 tools, 405 operations
Exposing all 405 operations as tools put about 84 000 tokens of definitions in front of every message, which left Claude Desktop unusable with it switched on. The list is now about 8 400. So the client sees:
25 core tools for libraries, search, items, recently added, continue watching, sessions, history, playlists, watched state, ratings, refreshing a section and the watchlist (
COREinsrc/plex_mcp/catalog.py)find_operation, which searches every operation by words and returns its route, summary and argumentsrun_operation, which runs any operation by nameget_result_page, which pages answers too large to send at once
The generated functions live in tools.py as before; they are recorded as operations and only the core set is registered as tools.
Two APIs, one server
Plex splits across the media server and the plex.tv cloud. The spec records which host each operation belongs to and the client routes on it, so a watchlist call reaches plex.tv while a library call reaches your server:
Host | Operations |
Your media server | 353 |
| 27 |
| 11 |
| 6 |
| 4 |
| 4 |
What is covered
Activities, Authentication, Butler, Collections, Content, DVRs, Devices, Download Queue, EPG, Events, General, Hubs, Library, Library Collections, Library Playlists, Live TV, Log, Play Queue, Playback, Playlist, Playlists, Plex, Preferences, Provider, Rate, Search, Status, Subscriptions, Timeline, Transcoder, UltraBlur, Updater, Users.
Setup
git clone https://github.com/rollecode/plex-mcp.git
cd plex-mcp
uv venv && uv pip install -e .export PLEX_URL=http://127.0.0.1:32400
export PLEX_TOKEN=... # see belowFind the token by opening any item in the Plex web app, choosing Get Info, then View XML: it is the X-Plex-Token in the address bar.
Claude Code
claude mcp add plex -- /path/to/plex-mcp/.venv/bin/plex-mcpNotes
Plex answers in XML unless asked for JSON, which the client does; a few endpoints ignore that and their raw XML comes back as text. Rating keys identify items, section keys identify libraries.
Hosting it
Running it over HTTP puts it in reach of Claude.ai as a custom connector, and of Claude Code on other machines. Three tiers, the same shape the other servers in this family use:
Tier | Port | What it does |
| 8590 | The server. No login of its own, never exposed |
nginx | 8591 | Front door, behind a Cloudflare Tunnel |
| 8592 | OAuth 2.1 sign-in, or a fixed bearer token |
npm install
node set-password.js 'a password for the sign-in page'
printf 'PLEX_URL=...\nPLEX_TOKEN=...\n' > ~/.config/plex-mcp/env
chmod 600 ~/.config/plex-mcp/envCopy systemd/*.service into /etc/systemd/system/, replacing YOUR_USER and the ISSUER hostname, then:
sudo systemctl enable --now plex-mcp plex-mcp-authPoint nginx/plex-mcp.conf at your own hostname and send the tunnel at 127.0.0.1:8591.
Claude.ai
Settings, Connectors, Add custom connector, URL https://plex-mcp.your-domain/mcp, client ID and secret blank. The sign-in page asks for the password set above.
Development
uv pip install -e . pytest ruff
.venv/bin/python -m pytest tests
.venv/bin/ruff check .Available Tools
28 toolscreate_actions_add_to_watchlistBIdempotent
Add to Watchlist.
POST /actions/addToWatchlist
Args: uri: The URI of the item to add or remove
Inputs: uri. Returns: result
create_actions_remove_from_watchlistCIdempotent
Remove from Watchlist.
POST /actions/removeFromWatchlist
Args: uri: The URI of the item to add or remove
Inputs: uri. Returns: result
create_library_sections_by_section_id_refreshBIdempotent
Refresh Section.
POST /library/sections/{sectionId}/refresh
Args: section_id: Section identifier force: Whether the update of metadata and items should be performed even if modification dates indicate the items have not change path: Restrict refresh to the specified path
Inputs: section_id (required), path, force. Returns: result
create_playlistsBIdempotent
Create a Playlist.
POST /playlists
Args:
uri: The content URI for what we're playing (e.g. library://...).
play_queue_id: To create a playlist from an existing play queue.
Inputs: uri, play_queue_id. Returns: result
find_operationARead-onlyIdempotent
Search all 405 Plex API operations, including those not exposed as tools.
Returns each match's name, route, summary and arguments. Run one with run_operation.
Args: query: Words describing what you want, such as "delete playlist item", "butler tasks" or "transcode sessions". limit: How many matches to return.
Inputs: query (required), limit. Returns: result
get_library_collections_by_collection_id_itemsBRead-onlyIdempotent
Get items in a collection.
GET /library/collections/{collectionId}/items
Args: collection_id: The collection id
Inputs: collection_id (required). Returns: result
get_library_metadata_by_id_childrenCRead-onlyIdempotent
Get Metadata Children.
GET /library/metadata/{id}/children
Args: id: The unique identifier of the item
Inputs: id (required). Returns: result
get_library_metadata_by_idsARead-onlyIdempotent
Get a metadata item.
GET /library/metadata/{ids}
Args:
ids: Comma-separated list of IDs
async_check_files: Determines if file check should be performed asynchronously. An activity is created to indicate progress. Default is false.
async_refresh_local_media_agent: Determines if local media agent refresh should be performed asynchronously. An activity is created to indicate progress. Default is false.
async_refresh_analysis: Determines if analysis refresh should be performed asynchronously. An activity is created to indicate progress. Default is false.
check_files: Determines if file check should be performed synchronously. Specifying asyncCheckFiles will cause this option to be ignored. Default is false.
skip_refresh: Determines if synchronous local media agent and analysis refresh should be skipped. Specifying async versions will cause synchronous versions to be skipped. Default is false.
check_file_availability: Determines if file existence check should be performed synchronously. Specifying checkFiles will imply this option. Default is false.
async_augment_metadata: Add metadata augmentations. An activity is created to indicate progress. Option will be ignored if specified by non-admin or if multiple metadata items are requested. Default is false.
augment_count: Number of augmentations to add. Requires asyncAugmentMetadata to be specified.
include_markers: Include intro/credits markers in the response
include_guids: Include external GUIDs (e.g. TMDB, TVDB) in the response
include_chapters: Include chapter data in the response
include_external_media: Include external/online media in the response
include_extras: Include trailers, behind-the-scenes, and other extras
include_related: Include related items in the response
include_on_deck: Include On Deck status in the response
include_popular_leaves: Include popular episodes in the response
include_reviews: Include user reviews in the response
include_stations: Include radio station data in the response
exclude_elements: Comma-separated list of elements to exclude from the response
exclude_fields: Comma-separated list of fields to exclude from the response
Inputs: ids (required), check_files, skip_refresh, augment_count, +17 more. Returns: result
get_library_metadata_by_ids_similarBRead-onlyIdempotent
Get similar items.
GET /library/metadata/{ids}/similar
Args: ids: Comma-separated list of IDs
Inputs: ids (required). Returns: result
get_library_sections_by_section_id_allBRead-onlyIdempotent
Get items in the section.
GET /library/sections/{sectionId}/all
Args: section_id: The id of the section include_meta: Adds the Meta object to the response include_guids: Adds the Guid object to the response include_collections: Include collection items in results include_external_media: Include external or online media include_advanced: Include advanced settings check_files: Verify file existence include_related: Include related items include_extras: Include trailers, behind-the-scenes, etc. include_popular_leaves: Include popular episodes include_concerts: Include concert items include_on_deck: Include On Deck status include_chapters: Include chapter markers include_preferences: Include user preferences include_bandwidths: Include bandwidth info include_loudness_ramps: Include loudness ramp data include_stations: Include radio station data include_external_ids: Include external GUIDs include_reviews: Include user reviews include_credits: Include full credits include_art: Force inclusion of artwork fields include_thumb: Force inclusion of thumbnail fields include_banner: Force inclusion of banner fields include_theme: Force inclusion of theme fields include_fields: Whitelist of fields to return exclude_fields: Blacklist of fields to omit async_augment_metadata: Async metadata augmentation async_refresh_local_media_agent: Async local media agent refresh nocache: Bypass cache skip_refresh: Skip synchronous refresh exclude_elements: Comma-separated list of elements to exclude from the response filters: General filtering expression. unwatched: Filter to unwatched only (1 = true). genre: Filter by genre. studio: Filter by studio. content_rating: Filter by content rating. resolution: Filter by resolution. year: Filter by year. first_character: Filter by first character of title.
Inputs: section_id (required), year, genre, studio, +35 more. Returns: result
get_library_sections_by_section_id_collectionsCRead-onlyIdempotent
Get collections in a section.
GET /library/sections/{sectionId}/collections
Args: section_id: Section identifier
Inputs: section_id (required). Returns: result
get_library_sections_by_section_id_unwatchedBRead-onlyIdempotent
Get Unwatched for Section.
GET /library/sections/{sectionId}/unwatched
Args: section_id: The unique identifier of the library section
Inputs: section_id (required). Returns: result
get_playlists_by_playlist_id_itemsARead-onlyIdempotent
Retrieve Playlist Contents.
GET /playlists/{playlistId}/items
Args: playlist_id: The ID of the playlist type: The metadata types of the item to return. Values past the first are only used in fetching items from the background processing playlist.
Inputs: playlist_id (required), type. Returns: result
get_result_pageARead-onlyIdempotent
Read more of a result that was too large to return in one piece.
Any tool whose answer is too large returns its first page with a
paging block. Pass that block's result_id here. Nothing is fetched
again: the stored result is paged, filtered and narrowed.
Args:
result_id: From the paging block of the earlier answer.
offset: First item to return, usually the previous next_offset.
limit: At most this many items. Fewer come back if they would not fit.
fields: Only these keys of each item. Dots reach nested keys, such as
"statistics.sizeOnDisk". The paging.fields list shows what exists.
match: Keep only items whose field contains this text, ignoring case,
for example {"title": "alien", "year": "1979"}.
path: Which list to page when the result holds several, as named in
paging.lists. Defaults to the largest.
Inputs: result_id (required), path, limit, match, +2 more. Returns: result
list_hubs_continue_watching_itemsBRead-onlyIdempotent
Get Continue Watching Items.
GET /hubs/continueWatching/items
Inputs: no named parameters. Returns: result
list_hubs_searchBRead-onlyIdempotent
Search Hub.
GET /hubs/search
Args: query: The query term section_id: This gives context to the search, and can result in re-ordering of search result hubs. limit: The number of items to return per hub. 3 if not specified include_collections: Include collection results in search hubs
Inputs: limit, query, section_id, include_collections. Returns: result
list_identityBRead-onlyIdempotent
Get PMS identity.
GET /identity
Inputs: no named parameters. Returns: result
list_library_recently_addedARead-onlyIdempotent
Get Global Recently Added.
GET /library/recentlyAdded
Inputs: no named parameters. Returns: result
list_library_sectionsBRead-onlyIdempotent
Get Library Sections (Fallback).
GET /library/sections/
Inputs: no named parameters. Returns: result
list_library_sections_watchlist_allBRead-onlyIdempotent
Get Watchlist.
GET /library/sections/watchlist/all
Inputs: no named parameters. Returns: result
list_playlistsCRead-onlyIdempotent
List playlists.
GET /playlists
Args: playlist_type: Limit to a type of playlist type: Filter by playlist type. Use 42 for optimized/conversion items.
Inputs: type, playlist_type. Returns: result
list_status_sessionsBRead-onlyIdempotent
List Sessions.
GET /status/sessions
Inputs: no named parameters. Returns: result
list_status_sessions_history_allARead-onlyIdempotent
List Playback History.
GET /status/sessions/history/all
Args:
account_id: The account id to restrict view history
viewed_at: The time period to restrict history (typically of the form viewedAt>=12456789)
library_section_id: The library section id to restrict view history
metadata_item_id: The metadata item to restrict view history (can provide the id for a show to see all of that show's view history). Note this is translated to metadata_items.id, parents.id, or grandparents.id internally depending on the metadata type.
sort: The field on which to sort. Multiple orderings can be specified separated by , and the direction specified following a : (desc or asc; asc is assumed if not provided). Note metadataItemID may not be used here.
exclude_elements: Comma-separated list of elements to exclude from the response
exclude_fields: Comma-separated list of fields to exclude from the response
include_fields: Whitelist of fields to return
include_elements: Whitelist of elements to include
viewed_at_query: Greater-than filter for viewedAt timestamp
viewed_at_query_2: Less-than filter for viewedAt timestamp
device_id: Filter by device ID
Inputs: sort, device_id, viewed_at, account_id, +8 more. Returns: result
run_operationADestructiveIdempotent
Run any Plex API operation by name, as found with find_operation.
Some operations change or delete things; check read_only in the
find_operation result before running one the user did not ask for.
Args: name: Operation name from find_operation. arguments: Its arguments as listed there, by name.
Inputs: name (required), arguments. Returns: result
update_playlists_by_playlist_id_itemsCIdempotent
Adding to a Playlist.
PUT /playlists/{playlistId}/items
Args: playlist_id: The ID of the playlist uri: The content URI for the playlist. play_queue_id: The play queue to add to a playlist.
Inputs: playlist_id (required), uri, play_queue_id. Returns: result
update_rateAIdempotent
Rate an item.
PUT /:/rate
Args:
identifier: The identifier of the media provider containing the media to rate. Typically com.plexapp.plugins.library
key: The key of the item to rate. This is the ratingKey found in metadata items
rating: The rating to give the item.
rated_at: The time when the rating occurred. If not present, interpreted as now.
Inputs: key, rating, rated_at, identifier. Returns: result
update_scrobbleBIdempotent
Mark an item as played.
PUT /:/scrobble
Args:
identifier: The identifier of the media provider containing the media to rate. Typically com.plexapp.plugins.library
key: The key of the item to rate. This is the ratingKey found in metadata items
uri: URI of the item to scrobble. Format is library://<section-uuid>/item/<url-encoded-key> or plex://movie/<guid> or plex://episode/<guid>.
Inputs: key, uri, identifier. Returns: result
update_unscrobbleBIdempotent
Mark an item as unplayed.
PUT /:/unscrobble
Args:
identifier: The identifier of the media provider containing the media to rate. Typically com.plexapp.plugins.library
key: The key of the item to rate. This is the ratingKey found in metadata items
uri: URI of the item to scrobble. Format is library://<section-uuid>/item/<url-encoded-key> or plex://movie/<guid> or plex://episode/<guid>.
Inputs: key, uri, identifier. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools map to distinct Plex endpoints (sections, metadata, playlists, sessions, scrobble/rate). Some blurring exists: get_library_metadata_by_id_children vs get_library_metadata_by_ids, get_library_sections_by_section_id_all vs list_library_sections, and the find_operation/run_operation pair can do anything any other tool does, so overlap is inherent.
Names follow a fairly predictable verb_path snake_case pattern (list_/get_/create_/update_ + route segments). Minor deviations: singular 'by_id' vs plural 'by_ids', get vs list used for analogous reads, and awkward appends like 'children' or '_all' at the end.
28 tools is on the heavy side for curation, and because find_operation/run_operation already expose all 405 API operations, several of the explicit tools are effectively redundant duplicates of the escape hatch. The set is usable but not tightly scoped.
The surface covers library browsing, playlists, sessions/history, search, scrobble/rate, watchlist and refresh, and run_operation makes the remaining API operations reachable, so no hard dead ends. Direct CRUD is patchy, though: playlist deletion, playlist item removal, and library section mutation require going through run_operation.
Maintenance
Related MCP Connectors
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
One workspace of tools for Claude and ChatGPT: connect 600+ apps, generate media, build tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLets AI assistants browse your libraries, search media, get viewing recommendations, check what's on deck, and more — all read-only against your local Plex instance.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables full management of a Plex Media Server via Claude, including browsing libraries, fixing metadata, managing collections, and more.-
- AlicenseNot gradedqualityCmaintenanceExposes every documented Plex Media Server API operation as a callable tool, plus curated tools for library browsing, media search and editing, playlists, collections, live sessions, user analytics, recommendations, watchlists, playback control and subtitles. Enables clients to query, automate and control a Plex server, discover owned servers and control playback clients through natural language.506 npmMIT
- AlicenseCqualityBmaintenanceEnables full control of Sonarr from Claude.ai and Claude Code by exposing all 234 v3 API operations as tools for managing media libraries.23523 npmMIT