mcp-plex-server 0.1.4

MCP server for Plex media discovery, search, and library management

mcp-plex

MCP server for Plex Media Server, focused on media discovery, search, and library management. 13 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 & Playlists

Tool	Parameters	Description
get_collections	library_name	List collections in a library.
get_playlists	(none)	List all playlists on the server.
get_playlist_items	rating_key	Get items in a playlist.

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