plex media server.com
plex media server.com logo

Plex Media Server

Integrates with Plex media servers to enable browsing, searching, and managing media libraries, including content queryi...

Created byApr 23, 2025

Plex MCP Server

A powerful Model-Controller-Protocol server for interacting with Plex Media Server, providing a standardized JSON-based interface for automation, scripting, and integration with other tools.

Overview

Plex MCP Server creates a unified API layer on top of the Plex Media Server API, offering:
  • **Standardized JSON responses** for compatibility with automation tools, AI systems, and other integrations
  • **Multiple transport methods** (stdio and SSE) for flexible integration options
  • **Rich command set** for managing libraries, collections, playlists, media, users, and more
  • **Error handling** with consistent response formats
  • **Easy integration** with automation platforms (like n8n) and custom scripts

Requirements

  • Python 3.8+
  • Plex Media Server with valid authentication token
  • Access to the Plex server (locally or remotely)

Installation

  1. Clone this repository
  1. Install the required dependencies: ``` pip install -r requirements.txt ```
  1. Create a `.env` file based on the `.env.example`: ``` cp .env.example .env ```
  1. Add your Plex server URL and token to the `.env` file: ``` PLEX_URL=http://your-plex-server:32400 PLEX_TOKEN=your-plex-token ```

Usage

The server can be run in two transport modes: stdio (Standard Input/Output) or SSE (Server-Sent Events). Each mode is suitable for different integration scenarios.

Running with stdio Transport

The stdio transport is ideal for direct integration with applications like Claude Desktop or Cursor. It accepts commands via standard input and outputs results to standard output in JSON format.
Basic command line usage:
or

Configuration Example for Claude Desktop/Cursor

Add this configuration to your application's settings:

Running with SSE Transport

The Server-Sent Events (SSE) transport provides a web-based interface for integration with web applications and services.
Start the server:
Default options:
  • Host: 0.0.0.0 (accessible from any network interface)
  • Port: 3001
  • SSE endpoint: `/sse`
  • Message endpoint: `/messages/`

Configuration Example for SSE Client

When the server is running in SSE mode, configure your client to connect using:
With SSE, you can connect to the server via web applications or tools that support SSE connections.

Command Modules

Library Module

  • List libraries
  • Get library statistics
  • Refresh libraries
  • Scan for new content
  • Get library details
  • Get recently added content
  • Get library contents

Media Module

  • Search for media
  • Get detailed media information
  • Edit media metadata
  • Delete media
  • Get and set artwork
  • List available artwork

Playlist Module

  • List playlists
  • Get playlist contents
  • Create playlists
  • Delete playlists
  • Add items to playlists
  • Remove items from playlists
  • Edit playlists
  • Upload custom poster images
  • Copy playlists to other users

Collection Module

  • List collections
  • Create collections
  • Add items to collections
  • Remove items from collections
  • Edit collections

User Module

  • Search for users
  • Get user information
  • Get user's on deck content
  • Get user watch history

Sessions Module

  • Get active sessions
  • Get media playback history

Server Module

  • Get Plex server logs
  • Get server information
  • Get bandwidth statistics
  • Get current resource usage
  • Get and run butler tasks
  • Get server alerts

Client Module

  • List clients
  • Get client details
  • Get client timelines
  • Get active clients
  • Start media playback
  • Control playback (play, pause, etc.)
  • Navigate client interfaces
  • Set audio/subtitle streams
**Note:** The Client Module functionality is currently limited and not fully implemented. Some features may not work as expected or may be incomplete.

Response Format

All commands return standardized JSON responses for maximum compatibility with various tools, automation platforms, and AI systems. This consistent structure makes it easy to process responses programmatically.
For successful operations, the response typically includes:
For errors, the response format is:
For multiple matches (when searching by title), results are returned as an array of objects with identifying information:

Debugging

For development and debugging, you can use the included `watcher.py` script which monitors for changes and automatically restarts the server.

License

[Include your license information here]