Files

Build and Push Docker Image / build (push) Failing after 0s

Details

Initial commit: Plex MCP server with 6 tools and API passthrough

- get_libraries: List all library sections
- search_library: Search for media by title
- get_metadata: Get detailed item info by rating key
- get_recently_added: Get recently added content
- refresh_library: Trigger library scan
- plex_api_call: Raw API passthrough for any endpoint
- search_api_docs: Search OpenAPI spec for endpoint documentation

Includes Docker support and Gitea Actions workflow for container builds.

2025-12-28 05:26:43 +00:00

2.8 KiB

Raw Blame History

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

2.8 KiB Raw Blame History