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

Library Browsing

Shows

Collections

Playlists

Watch State

Management

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