home / mcp / plex mcp server

Plex MCP Server

Provides a unified, JSON-based interface over Plex Media Server for automation and integration.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "vladimir-tutin-plex-mcp-server": {
      "command": "python3",
      "args": [
        "-m",
        "plex_mcp"
      ],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your-plex-token",
        "PLEX_USERNAME": "Administrator"
      }
    }
  }
}

Plex MCP Server provides a standardized JSON-based interface on top of the Plex Media Server API, enabling automation, scripting, and seamless integration with other tools. It supports multiple transport methods and a rich set of commands to manage libraries, media, playlists, users, and more, all with consistent responses for easier automation.

How to use

You run the Plex MCP Server locally and connect to it from your MCP client or automation tool. Use the stdio transport for direct, script-driven workflows, or choose SSE to interact from web applications and services. Once running, you can command the server to list libraries, manage media, create playlists, access user data, and perform operational tasks with consistent JSON responses.

Typical usage patterns include: starting the server, selecting the transport method that fits your environment, connecting your client, and issuing actions such as scanning for new content, refreshing libraries, or controlling playback via the Client module. All actions return structured JSON responses to simplify integration with automation platforms and AI workflows.

How to install

Prerequisites you need to prepare before running the server:

- Python 3.8+

- Plex Media Server with a valid authentication token

Install steps you should follow in order:

1. Install Python dependencies

2. Run the server

Exact commands shown here reflect the provided setup options. Use the transport you prefer when starting the server.

Transport and runtime configuration

The server can run in either stdio or SSE mode. Choose stdio for direct command-line or application integrations, or SSE for web-based workflows and web app integrations.

A) StdIO transport runs in-process and communicates through standard input and output. Use Python to launch the server with the desired transport.

B) SSE transport exposes a web-based interface and endpoints for continuous events.

Configuration detail

Crucial environment variables you will set for Plex integration include the Plex server URL and authentication token. You will supply these when launching the server so it can access your Plex Media Server.

If you use the stdio transport, the runtime can be started in one of the following ways:

python3 -m plex_mcp

Or, to start with the alternate stdio entry point that specifies transport explicitly:

python3 plex_mcp_server.py --transport stdio

If you prefer SSE, start the server with the SSE transport and specify the host and port to listen on:

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

Notes on configuration examples

Examples below show how to configure clients to connect to the local server when using stdio transport.

Command modules overview

Library Module: manage libraries, refresh content, and fetch details.

Media Module: search, edit, and manage media metadata and artwork.

Playlist Module: create and edit playlists, and manage items.

Collection Module: create and manage collections, and add or remove items.

User Module: search and retrieve user information and watch history.

Sessions Module: view active sessions and playback history.

Server Module: access server logs, information, and resource usage.

Client Module: list and control connected clients and playback.

Response format and debugging

All commands return standardized JSON responses to help you integrate with automation tools and AI systems. A successful response includes a success field and relevant data. Errors are returned with a clear error message.

For development and debugging, you can use a watcher utility to monitor for changes and automatically restart the server.

Available tools

Library operations

List libraries, refresh libraries, scan for new content, and fetch library details.

Media operations

Search media, get detailed info, edit metadata, delete media, and manage artwork.

Playlist operations

Create, delete, edit playlists, add or remove items, and upload posters.

Collection operations

List, create, add items, remove items, and edit collections.

User operations

Search for users, retrieve user information, and access on-deck content and history.

Sessions and playback

Get active sessions and playback history.

Server operations

Fetch server logs, info, bandwidth, and resource usage; run server tasks.