Skip to main content
Glama

Plex MCP server

Version Python Plex Coverage

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.

WARNING

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

niavasha/plex-mcp-server

~40

10 %

tdabasinskas/plex-mcp-server

libraries, playlists, clients

partial

eddmann/plex-mcp

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.py

A 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

list_*

Read a collection

list_library_sections, list_status_sessions

get_*_by_id

Read one record

get_library_metadata_by_rating_key

create_*

POST

create_playlists, create_library_sections

update_*

PUT

update_playlists_by_playlist_id

delete_*

DELETE

delete_playlists_by_playlist_id

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 (CORE in src/plex_mcp/catalog.py)

  • find_operation, which searches every operation by words and returns its route, summary and arguments

  • run_operation, which runs any operation by name

  • get_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

plex.tv/api/v2

27

plex.tv/api

11

plex.tv

6

discover.provider.plex.tv

4

clients.plex.tv/api/v2

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 below

Find 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-mcp

Notes

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

plex-mcp

8590

The server. No login of its own, never exposed

nginx

8591

Front door, behind a Cloudflare Tunnel

auth-server.js

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/env

Copy systemd/*.service into /etc/systemd/system/, replacing YOUR_USER and the ISSUER hostname, then:

sudo systemctl enable --now plex-mcp plex-mcp-auth

Point 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 tools
create_actions_add_to_watchlistB
Idempotent

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_watchlistC
Idempotent

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_refreshB
Idempotent

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_playlistsB
Idempotent

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_operationA
Read-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_itemsB
Read-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_childrenC
Read-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_idsA
Read-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_similarB
Read-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_allB
Read-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_collectionsC
Read-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_unwatchedB
Read-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_itemsA
Read-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_pageA
Read-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_itemsB
Read-onlyIdempotent

Get Continue Watching Items.

GET /hubs/continueWatching/items

Inputs: no named parameters. Returns: result

list_identityB
Read-onlyIdempotent

Get PMS identity.

GET /identity

Inputs: no named parameters. Returns: result

list_library_recently_addedA
Read-onlyIdempotent

Get Global Recently Added.

GET /library/recentlyAdded

Inputs: no named parameters. Returns: result

list_library_sectionsB
Read-onlyIdempotent

Get Library Sections (Fallback).

GET /library/sections/

Inputs: no named parameters. Returns: result

list_library_sections_watchlist_allB
Read-onlyIdempotent

Get Watchlist.

GET /library/sections/watchlist/all

Inputs: no named parameters. Returns: result

list_playlistsC
Read-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_sessionsB
Read-onlyIdempotent

List Sessions.

GET /status/sessions

Inputs: no named parameters. Returns: result

list_status_sessions_history_allA
Read-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_operationA
DestructiveIdempotent

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_itemsC
Idempotent

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_rateA
Idempotent

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_scrobbleB
Idempotent

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_unscrobbleB
Idempotent

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

    B3.3/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets 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.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables full management of a Plex Media Server via Claude, including browsing libraries, fixing metadata, managing collections, and more.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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 npm
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables full control of Sonarr from Claude.ai and Claude Code by exposing all 234 v3 API operations as tools for managing media libraries.
      235
      23 npm
      MIT