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+
• uv
• A running Plex Media Server
• A Plex authentication token

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