Plex MCP Server

A lightweight MCP (Model Context Protocol) server for interacting with Plex Media Server.

Features

• 5 Specific Tools for common operations:

  • get_libraries - List all library sections
  • search_library - Search for media by title
  • get_metadata - Get detailed item information
  • get_recently_added - Get recently added content
  • refresh_library - Trigger library scan for new content

• API Pass-through (plex_api_call) for accessing any of the 190+ Plex API endpoints

• Documentation Resources:

  • plex://api-reference - Curated API quick reference
  • search_api_docs - Search the full OpenAPI specification

Quick Start

Prerequisites

• Python 3.11+
• Plex Media Server with API access
• Plex authentication token (how to find your token)

Installation

# Clone the repository
cd plex-mcp-custom

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your Plex URL and token

Configuration

Edit .env with your Plex settings:

PLEX_URL=http://your-plex-server:32400
PLEX_TOKEN=your-plex-token
PLEX_CLIENT_ID=plex-mcp-server
PORT=8000

Running

# Direct
python server.py

# Or with uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000

Docker

# Build and run
docker-compose up -d

# Or build manually
docker build -t plex-mcp .
docker run -d --env-file .env -p 8000:8000 plex-mcp

Usage

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "plex": {
      "url": "http://localhost:8000/mcp/v1"
    }
  }
}

Tool Examples

List libraries:

get_libraries()

Search for a movie:

search_library(query="Inception", limit=5)

Get item details:

get_metadata(rating_key="12345", include_children=true)

Trigger library scan:

refresh_library(section_id=1)

Raw API call (mark as watched):

plex_api_call(
  endpoint="/:scrobble",
  params='{"key": "12345", "identifier": "com.plexapp.plugins.library"}'
)

Finding Endpoints

Use search_api_docs to find endpoints for specific operations:

search_api_docs(query="playlist")
search_api_docs(query="transcode")
search_api_docs(query="rating")

Or access the curated reference via the plex://api-reference resource.

API Reference

See docs/api_reference.md for a curated guide to common endpoints.

The full OpenAPI specification is available in openapi.json and can be searched via the search_api_docs tool.

Health Check

curl http://localhost:8000/health

Returns:

{"status": "ok", "plex_connected": true}

License

MIT