Plex MCP

plex-mcp

An MCP server that gives your AI assistant a complete picture of your Plex Media Server: every library, watched and unwatched, every household member's watch history, plus safe curation writes (playlists, collections, watched state, ratings, the plex.tv watchlist).

It talks to Plex's HTTP API directly (no client library, 2 runtime dependencies), ships as an npm package and a Docker image, and is tested offline.

Nothing in this server can delete, move, or modify media files or metadata.

What you can ask

• "Which Scorsese films haven't I seen?"
• "Pick three unwatched 90s thrillers under 100 minutes."
• "What should I continue tonight?" (the next unwatched episode of each show)
• "Has anyone else watched Severance? Who's furthest along?"
• "What did the kids watch this month?"
• "What's new in the TV library this week?"
• "Make a collection of everything Denis Villeneuve directed that I haven't rated."

Quick start

Requires Node 22+ and a Plex Media Server you own.

1. Sign in and get your credentials (plex.tv PIN flow, no token hunting):

npx @dustinhansen/plex-mcp login

It prints a link, waits for you to approve it in the browser, then prints PLEX_URL=… and PLEX_TOKEN=…. Add --write to append both lines to a file as well. The file holds your token, so on macOS and Linux a new one is created readable by you only. An existing file keeps its permissions. --write refuses a file name that starts with -, so pass it as ./-name. (Prefer the manual route? Plex Web → play any item → ⋮ → Get Info → View XML → X-Plex-Token in the URL.)

2. Add it to your client. Any MCP client that can launch a local (stdio) server works. Most of them take the server as a command, its arguments and an environment. Here are 2 CLIs, for example:

# Claude Code

claude mcp add plex -e PLEX_URL=http:// :32400 -e PLEX_TOKEN= -- npx -y @dustinhansen/plex-mcp

Codex

codex mcp add plex --env PLEX_URL=http:// :32400 --env PLEX_TOKEN= -- npx -y @dustinhansen/plex-mcp

Clients configured with a JSON file (Claude Desktop, Cursor, and any client that reads a .mcp.json) mostly use this shape. Your client's docs say where the file lives and whether it names the top-level key differently:

{

"mcpServers": { "plex": { "command": "npx", "args": ["-y", "@dustinhansen/plex-mcp"], "env": { "PLEX_URL": "http:// :32400", "PLEX_TOKEN": " " } } } }

Assistants that run in a browser or on a phone (claude.ai, ChatGPT) can't launch a local process. They need the server in HTTP mode, reachable from the vendor's cloud. See HTTP mode and Docker and docs/remote-access.md.

Use the server owner's admin token if you want every user's watch history.

Tools

The server registers 22 tools by default, and the optional ones below add up to 4 more. Each tool declares a title and all 4 MCP annotations (read-only, destructive, idempotent, open-world). The spec tells clients to treat annotations as hints, so the Safety model rests on what the server registers.

Browse & read

Discover

There are also two MCP prompts, movie_night and whats_new, and a plex://libraries resource.

History & household

continue_watching, list_media, random_pick and library_stats accept a user argument to see the library as a Plex Home user (their watched state, their on-deck). Plex only allows this for Home (managed) users. For friends, watch_history is the view that works for everyone.

Curate (writes)

Registered unless PLEX_READ_ONLY=1.

manage_watchlist resolves each ratingKey to the Plex GUID plex.tv identifies the item by. It takes movies and shows only, the kinds a Plex watchlist offers, and refuses an item matched by a legacy agent (which has no Plex GUID). Both checks run before anything is sent.

Optional: playback (off by default)

Set PLEX_ALLOW_PLAYBACK=1 to register list_clients and play_item ("play this album on my phone"). Both tools use Plex's player-control API, so the target must be a player that advertises itself to the server. We have tested playback with Plexamp. Current Plex apps for TVs and desktops may not show up in list_clients at all: Plex for Apple TV and Plex for Mac did not, even with the app open. Off by default because it's the one thing here that touches the real world. PLEX_READ_ONLY=1 keeps them unregistered even when this is set.

Optional: Tautulli

Set TAUTULLI_URL and TAUTULLI_API_KEY to add tautulli_stats (home stats: most watched, most active users, popular items over a period) and tautulli_history (per-play records with platform, player, and percent watched). Plex's own history covers the basics. Tautulli adds the detail most admins already collect. They need Tautulli 2.18.0 or later, the first release that reads the API key from a request header.

Safety model

• No media mutations. There is no code path that deletes, moves, renames, or edits media files or metadata. Playlist/collection deletion removes the grouping only.
• Writes are explicit. Every write names its targets: items by ratingKey, a playlist or collection by id, and a library by title. A library scan can narrow to one folder. Creating a collection names its library too: several read tools default to Movies because a read changes nothing, but a write never picks its own target. The collection's kind is not a target: it follows the named library (movie, show, or album for a music library), so it always agrees with where the collection goes. A kind that contradicts the library is refused before the write, and so is a library type that holds no collection kind the tool offers. Nothing operates on "all matches".
• Playback is opt-in via an environment variable. The tools aren't registered without it.
• `PLEX_READ_ONLY=1` removes every write. The curation writes and the playback tools are not registered, whatever PLEX_ALLOW_PLAYBACK says, so a client sees only reads. The Tautulli tools are reads and stay. The restriction wins over the opt-in because a server set up to change nothing should not start changing things when another variable is added. Any value other than 1, 0 or empty stops the server rather than starting it with writes.
• Ids are a run of digits. A tool refuses any ratingKey, playlist id or collection id with anything else in it before the request reaches Plex (the client also refuses a request path that does not resolve to itself). We made this decision because a tool puts the id into the request path, and Plex marks an item watched, rates it and refreshes a library over GET. An id carrying .. or ? could turn a read into one of those writes, even with PLEX_READ_ONLY=1. We refuse a bad id rather than encode it, because no real Plex id needs encoding.
• Errors never echo upstream response bodies from Plex, plex.tv or Tautulli, which can contain server paths and configuration. A failed request names the upstream, the path and either the HTTP status or the network cause, such as `Plex unreachable (E