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
2. Install the required dependencies:

   pip install -r requirements.txt
   

3. Create a .env file based on the .env.example:

   cp .env.example .env
   

4. 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:

python3 -m plex_mcp

or

python3 plex_mcp_server.py --transport stdio

Configuration Example for Claude Desktop/Cursor

Add this configuration to your application's settings:

{
  "plex": {
    "command": "python",
    "args": [
      "C://Users//User//Documents//plex-mcp-server//plex_mcp_server.py",
      "--transport=stdio"
    ],
    "env": {
      "PLEX_URL":"http://localhost:32400",
      "PLEX_TOKEN":"av3khi56h634v3",
      "PLEX_USERNAME:"Administrator"
    }
  }
}

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:

python3 plex_mcp_server.py --transport sse --host 0.0.0.0 --port 3001

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:

{
  "plex": {
    "url": "http://localhost:3001/sse"
  }
}

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:

{
  "success_field": true,
  "relevant_data": "value",
  "additional_info": {}
}

For errors, the response format is:

{
  "error": "Error message describing what went wrong"
}

For multiple matches (when searching by title), results are returned as an array of objects with identifying information:

[
  {
    "title": "Item Title",
    "id": 12345,
    "type": "movie",
    "year": 2023
  },
  {
    "title": "Another Item",
    "id": 67890,
    "type": "show",
    "year": 2022
  }
]

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]