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
Clone this repository
Install the required dependencies:
```
pip install -r requirements.txt
```
Create a `.env` file based on the `.env.example`:
```
cp .env.example .env
```
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.