Plex MCP Server

🚀 Plex MCP Server

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

🚀 Quick Start

Plex MCP Server creates a unified API layer on top of the Plex Media Server API, offering:

• Standardized JSON responses: Ensuring compatibility with automation tools, AI systems, and other integrations.
• Multiple transport methods (Standard Input/Output and SSE): For flexible integration options.
• Rich command sets: For managing libraries, collections, playlists, media, users, etc.
• Consistent error handling format.
• Easy integration with automation platforms (such as n8n) and custom scripts.

✨ Features

Requirements

• Python 3.8+
• A Plex Media Server with a valid authentication token.
• Access to the Plex server (local or remote).

📦 Installation

1. Clone this repository.
2. Install the required dependencies:

   pip install -r requirements.txt
   

3. Create a .env file based on .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 Examples

Basic Usage

Standard Input/Output (stdio) Mode

Start the server with the following command:

python server.py

SSE Mode

Start the server with the following command:

python sse_server.py

Advanced Usage

The server provides various command modules for different operations.

Library Module

• add_library: Add a new library.
• remove_library: Delete an existing library.
• list_libraries: List all libraries.
• update_library: Update the configuration of a specific library.

Media Module

• search_media: Search for media by title, type, or year.
• get_media_info: Get detailed information about specific media.
• add_media: Add new media to a library.
• remove_media: Remove specific media from a library.

Playlist Module

• create_playlist: Create a new playlist.
• delete_playlist: Delete an existing playlist.
• add_to_playlist: Add media to a playlist.
• remove_from_playlist: Remove media from a playlist.

📚 Documentation

Response Format

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 the problem that occurred"
}

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

[
  {
    "title": "Item title",
    "id": 12345,
    "type": "Movie",
    "year": 2023
  },
  {
    "title": "Another item",
    "id": 67890,
    "type": "TV Show",
    "year": 2022
  }
]

Debugging

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

📄 License

[Include your license information here]