Plex MCP

🚀 Plex MCP Server

A Python-based MCP server integrated with the Plex Media Server API for movie searching and playlist management.

🔍 Features

• Integrates with the Plex Media Server API to search for movies and manage playlists.
• Uses the PlexAPI library to interact seamlessly with the Plex server.

📷 Screenshots

1. Search for Movies by Director in the PLEX Library

Search for movies in your PLEX library by specifying the director's name. For example, searching for "Alfred Hitchcock" will return a list of his movies in your library.

2. Find Missing Movies by a Director

Identify movies by a specific director that are not in your PLEX library. This helps you discover gaps in your collection.

3. Create a Playlist in Your PLEX Library

Create a new playlist in your PLEX library using the searched movies. This makes it easy to organize your library.

📦 Installation

Prerequisites

• Python 3.8 or higher
• uv package manager
• A Plex Media Server with API access

Installation Methods

Automatic Installation via Smithery

To automatically install the Plex Media Server integration for the Claude desktop via Smithery:

npx -y @smithery/cli install @djbriane/plex-mcp --client claude

Manual Installation

1. Clone this repository:

   git clone <repository-url>
   cd plex-mcp
   

2. Install dependencies using uv:

   uv venv
   source .venv/bin/activate
   uv install
   

3. Run the server:

   uv run python src/main.py
   

⚙️ Configuration

Environment Variables

Create a .env file and add the following content:

PLEX_SERVER_URL=https://your-plex-server-url:32400
PLEX_TOKEN=yourPlexTokenHere

Usage

After running the server, you can interact with Plex via the API or the web interface.

📜 Command List

The following are the main commands supported by the Plex MCP server:

🧪 Integration Testing

End-to-End Testing

Run the following command in the project root directory to perform end-to-end testing:

uv run pytest tests/

Integration Testing

To run integration tests, first create a .env file containing the Plex configuration, then run:

uv run pytest -m integration

📝 Code Style and Conventions

• Module Structure: Use clear section headings to distinguish imports, logging setup, utility functions, class definitions, global helpers, and the main execution part (protected by if __name__ == "__main__":).
• Naming Conventions: Use CamelCase for class definitions and lower_snake_case for functions, variables, and fixtures. In tests, list built-in fixtures (e.g., monkeypatch) before custom fixtures.
• Documentation and Comments: Each module, class, and function contains a concise docstring, and inline comments are added for complex logic.
• Error Handling and Logging: Use Python's logging module with consistent error messages (prefixed with "ERROR:") and explicit exception handling.
• Asynchronous Mode: Define I/O-bound functions as asynchronous and use asyncio.to_thread() when handling blocking operations.

This documentation details the features, installation, configuration, usage, and development conventions of the Plex MCP server. By following these guidelines, you can easily integrate and manage your PLEX media library.