Plex MCP Server

An MCP server for managing Plex libraries, media, and playback from Claude, ChatGPT, and other MCP clients.

Features

• JSON responses: Structured results for Plex operations.
• Multiple Transports: Supports stdio, SSE (Server-Sent Events), and Streamable HTTP.
• Comprehensive Control: Manage libraries, media, collections, playlists, clients, and users.
• Remote Ready: Built-in OAuth 2.1 support for integration with remote AI platforms like Claude.ai.
• Admin Tools: Access logs, monitor bandwidth, and run Butler tasks.

Installation

Option 1: Using uv (Recommended)

Run directly without installation:

uvx plex-mcp-server --transport stdio --plex-url http://your-server:32400 --plex-token your-token

Option 2: Install via pip

pip install plex-mcp-server

Option 3: Development / Source

git clone https://github.com/vladimir-tutin/plex-mcp-server.git
cd plex-mcp-server
pip install -e .

Option 4: Docker

The published image is ghcr.io/vladimir-tutin/plex-mcp-server:latest for Linux amd64 and arm64. It runs as a non-root user and serves Streamable HTTP at /mcp and legacy SSE at /sse. No media folders need to be mounted: it uses Plex's API.

Choose Docker Compose or Unraid, then follow Public HTTPS access for hosted clients such as Claude.ai or ChatGPT.

Docker Compose

git clone https://github.com/vladimir-tutin/plex-mcp-server.git
cd plex-mcp-server
cp .env.docker.example .env

Edit .env before starting. For a trusted LAN deployment, for example:

PLEX_URL=http://192.168.1.10:32400
PLEX_TOKEN=your-plex-token
MCP_BIND_ADDRESS=192.168.1.20
MCP_PUBLISHED_PORT=3001
MCP_SERVER_URL=http://192.168.1.20:3001
MCP_OAUTH_ENABLED=false

Replace 192.168.1.10 with the Plex address and 192.168.1.20 with the Docker host's address. Without OAuth, anyone who can reach this port can use the tools. The supplied example file defaults to loopback (127.0.0.1) instead, for access from the Docker host only. Keep .env private.

docker compose pull
docker compose up -d --no-build
docker compose logs -f

The LAN example's client URL is http://192.168.1.20:3001/mcp. Hosted clients need a reachable HTTPS endpoint; follow Public HTTPS access.

Unraid

In Docker → Add Container, enter:

Use Add another Path, Port, Variable, Label or Device to add a Port: container port 3001, an unused host port such as 3001, connection type TCP. Then add each of these as a Variable, using the exact key shown:

Use your Unraid IP and chosen host port in MCP_SERVER_URL. The Name of a variable is a display label; its Key must match the table. No .env file or media path mapping is required when entering variables in Unraid.

Click Apply. For this example, connect a LAN client to http://192.168.1.20:3001/mcp. The endpoint speaks MCP; it is not a browser dashboard. See Unraid's container configuration guide for managing variables and port mappings.

MCP_BIND_ADDRESS and MCP_PUBLISHED_PORT are settings used by this repository's Compose file. In Unraid, configure the port mapping in the form instead; adding those two variables does not change Unraid's published port.

Public HTTPS access

Setting MCP_SERVER_URL does not create DNS records, configure HTTPS, or publish the container. Complete these steps before connecting a hosted client:

1. Create an OAuth provider using Remote Access & OAuth.

2. Set these values in Compose's .env, or add them as Variables in Unraid:

   MCP_SERVER_URL=https://plexmcp.example.com
   MCP_OAUTH_ENABLED=true
   MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
   MCP_OAUTH_AUDIENCE=your-oauth-client-id
   

   Keep PLEX_URL and PLEX_TOKEN set as above. These are separate from your OAuth credentials. MCP_SERVER_URL is the public base URL, without /mcp or /sse. MCP_OAUTH_ISSUER is the provider's exact issuer URL, including its path and trailing slash.

3. Point the public hostname at your reverse proxy and configure a valid HTTPS certificate. Forward that hostname to the MCP container's published address, for example http://192.168.1.20:3001. This is the Docker/Unraid host and host port, not Plex's port 32400 or Authentik's address.

4. Forward all paths on that hostname unchanged, preserve the public Host and Authorization headers, and allow streaming responses without buffering. With Compose, the published address must be reachable by the proxy: use the Docker host's LAN address when the proxy runs elsewhere. A proxy in another container cannot reach this container through its own 127.0.0.1.

5. Let requests reach the MCP server's OAuth middleware rather than intercepting them with a browser-login page at the proxy. This includes /mcp, /sse, /messages/, /.well-known/ discovery paths, /authorize, and /token. The MCP server validates bearer tokens; Authentik handles the OAuth login.

6. Apply the Unraid changes, or run docker compose up -d --no-build after editing .env. Configure clients with https://plexmcp.example.com/mcp (Streamable HTTP) or https://plexmcp.example.com/sse (legacy SSE).

With OAuth enabled, an unauthenticated request to /mcp or /sse should return 401, while /.well-known/oauth-protected-resource should return JSON. A proxy login page or a 502 indicates the request is not reaching the expected MCP handler. Finish by signing in from your client and asking it to list your Plex libraries.

When moving an existing deployment, update the reverse proxy's upstream to the new host and port. You can retain the public MCP URL and client URLs. If the OAuth provider also moves, preserve its issuer URL and configuration or update MCP_OAUTH_ISSUER and the client credentials to match.

Updating or building the image

latest tracks published releases; edge tracks main. Use a version tag such as 1.2.0 to pin a release. Running containers do not update automatically.

For Compose, update with:

docker compose pull
docker compose up -d --no-build

To build from source, run docker compose build --pull, then docker compose up -d --no-build.

To run the published image without Compose, prepare .env with the server variables above and choose the host binding explicitly:

docker run -d --name plex-mcp-server --restart unless-stopped --init \
  --env-file .env -p 127.0.0.1:3001:3001 ghcr.io/vladimir-tutin/plex-mcp-server:latest

This command publishes on loopback only. For standalone SSE, append --transport sse --host 0.0.0.0 --port 3001. For stdio, use docker run --rm -i --env-file .env ghcr.io/vladimir-tutin/plex-mcp-server:latest --transport stdio without publishing a port.

Configuration

For containers, use the Docker setup. The following options also apply to direct Python installations. PLEX_URL points to Plex; MCP_SERVER_URL is the address of this MCP service. Inside a container, localhost refers to the container itself, so use a reachable network address for Plex.

Set your Plex server URL and Token using one of these methods:

1. Command Line Arguments

plex-mcp-server --plex-url "http://192.168.1.10:32400" --plex-token "ABC123XYZ"

2. Environment Variables (.env)

Create a .env file in the current directory or ~/.config/plex-mcp-server/.env:

PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-authentication-token
MCP_OAUTH_ENABLED=false

For OAuth settings, see Remote Access & OAuth.

3. MCP Client Config

Example for Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plex": {
      "command": "uvx",
      "args": [
        "plex-mcp-server",
        "--transport",
        "stdio",
        "--plex-url",
        "http://your-server:32400",
        "--plex-token",
        "your-token"
      ]
    }
  }
}

Remote servers from stdio-only clients

If your client only supports launching a local stdio process, use mcp-remote to connect it to a remote Plex MCP server. Install Node.js (which provides npx) on the client machine, then use:

{
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://plexmcp.example.com/mcp"]
    }
  }
}

Use /mcp when the server runs with --transport streamable-http. For an SSE deployment, use /sse instead. For plain HTTP on a trusted private network, append "--allow-http" to the arguments. If OAuth is enabled, follow the bridge's OAuth configuration instructions, including any required client credentials and callback registration.

Clients with native remote HTTP support can connect directly to /mcp and do not need Node.js, npx, or this bridge. The local stdio setup above also needs no bridge.

4. Claude Connector Installation

Go to https://claude.ai/settings/connectors and add a new connector with the following settings:

• Name: Plex MCP
• URL: https://plexmcp.example.com/sse for SSE, or https://plexmcp.example.com/mcp when running with --transport streamable-http.
• If OAuth is enabled, enter your provider's Client ID and Client Secret in the advanced settings and complete sign-in.

Register Claude's callback in your OAuth provider: https://claude.ai/api/mcp/auth_callback. See Remote Access & OAuth for provider and reverse-proxy configuration.

5. ChatGPT Connector Installation

Start the server with --transport streamable-http and make it reachable at a public HTTPS URL. In ChatGPT's plugin settings, choose Add custom MCP server:

• Name: Plex MCP
• Server URL: https://plexmcp.example.com/mcp
• Authentication: OAuth if enabled on the server; otherwise None.
• For a confidential OAuth client, open Advanced OAuth settings and supply your provider's Client ID and Client Secret. These are separate from your Plex token.

The screenshot shows where to find the OAuth settings if your server requires them. It uses a placeholder server URL, so discovery fails in this example. Use your real server URL and the token endpoint authentication method required by your provider.

Register the exact ChatGPT callback URL with your OAuth provider. It can look like https://chatgpt.com/connector/oauth/<callback-id>; use the value requested by your connection, not the literal placeholder. Create the plugin, complete sign-in, and refresh its tools. Test it by asking ChatGPT to list your Plex libraries.

For reverse-proxy routing, see Public HTTPS access.

The website plugin and a local Codex MCP entry are separate connections. For local Codex OAuth configuration, see the client setup instructions.

Streamable HTTP

Start the server with --transport streamable-http to expose /mcp:

plex-mcp-server --transport streamable-http --port 3001 --server-url https://plexmcp.example.com

Configure your client with https://plexmcp.example.com/mcp. This mode also keeps the legacy /sse and /messages/ endpoints available for existing clients. The default transport remains SSE; --transport stdio is also supported.

OAuth is optional on both HTTP transports. Enable it with --oauth-enabled or MCP_OAUTH_ENABLED=true, using the issuer settings below. Without OAuth, anyone who can reach the endpoints can call the tools; use an appropriate network boundary.

Both SSE and Streamable HTTP validate Host and Origin headers to block DNS-rebinding attacks (a malicious web page driving your server through your browser). --server-url (or MCP_SERVER_URL) permits your public hostname and origin even with OAuth disabled. For additional proxy names, LAN addresses, or browser origins, set comma-separated MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS (e.g. MCP_ALLOWED_HOSTS=192.168.1.20:3001). Loopback hosts are allowed by default. If a remote client gets 421 Invalid Host header, add its host and port to MCP_ALLOWED_HOSTS. For a rejected browser origin, add the full origin (scheme, host, and port) to MCP_ALLOWED_ORIGINS.

Remote Access & OAuth

OAuth protects both HTTP transports. The following setup uses Authentik as the identity provider.

How it works

The MCP server acts as the OAuth front door: clients discover it via /.well-known/oauth-protected-resource, are sent to /authorize (which redirects to your identity provider), and exchange codes at /token (which the server proxies to the provider). Clients therefore only ever need your MCP server URL plus the provider's Client ID / Secret. The browser visits the provider to complete sign-in. Access tokens are JWTs validated against the provider's JWKS; the server checks signature, expiry, issuer, and (optionally) audience on every request, on both SSE and Streamable HTTP.

1. Create an OAuth provider (Authentik example)

1. Providers → Create → OAuth2/OpenID Provider. Client type Confidential, signing key set (RS256). Note the Client ID and Client Secret.

2. Redirect URIs — add one entry per client you plan to use. These are the values seen in practice:

   Client	Redirect URI
   Claude.ai / Claude Desktop	https://claude.ai/api/mcp/auth_callback
   ChatGPT connector	https://chatgpt.com/connector/oauth/<connector-id> — shown in the connector dialog
   Codex CLI / local tools	loopback, random port: regex ^http://127\.0\.0\.1:[0-9]+/callback/<callback-id>$

   Keep this list tight. A catch-all like .* lets anyone who can get you to click a link capture an authorization code.

3. Applications → Create, bind it to the provider, and bind an access policy (your user or group). Any Authentik user who can authorize this application gets full control of Plex — there are no per-user roles inside the MCP server.

4. Copy the provider's OpenID Configuration Issuer URL, e.g. https://auth.example.com/application/o/plexmcp-oauth/ (trailing slash included).

2. Configure the server

For Docker or Unraid, enter these as environment variables using the public HTTPS setup, which also covers DNS and the reverse proxy.

MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
MCP_SERVER_URL=https://plexmcp.example.com
MCP_OAUTH_AUDIENCE=<Client ID>        # optional, recommended

or the equivalent flags: --oauth-enabled --oauth-issuer … --server-url … --oauth-audience ….

• MCP_SERVER_URL must be the public HTTPS URL clients reach; it also becomes the allowed Host/Origin for DNS-rebinding protection. Use the base URL without /mcp or /sse; HTTPS is provided by your reverse proxy.
• MCP_OAUTH_AUDIENCE makes the server reject tokens minted for any other client of the same provider. Set it to the Client ID from step 1. Leaving it unset disables audience validation for compatibility with existing deployments.

3. Configure each client

Use the Client ID and Secret from step 1 and one of these URLs:

Clients configured with /mcp use Streamable HTTP; /sse uses the legacy transport. Both are protected identically.

Discovery Endpoints

When OAuth is active, the following standard endpoints are exposed without authentication:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server
• /authorize (redirects to the provider) and /token (proxied to the provider)

Command Reference

Library Module

Tools for exploring and managing your Plex libraries.

To list watched movies currently in your library (rather than playback history):

{"library_name": "Movies", "watched": true, "offset": 0, "limit": 50}

Each result includes media_id (Plex's ratingKey) for looking up or deleting that specific item. The default page size is 50; increase offset to retrieve later pages. totalItems is the count matching the server-side filters, not just the current page. Watch state belongs to the user represented by PLEX_TOKEN.

Movie results also include inProgress and progressPercent, based on Plex's saved playback offset, even if the movie is absent from Continue Watching. inProgress is true when that offset is positive; it does not mean the movie is currently playing. progressPercent is the saved position as a percentage of duration, rounded to one decimal and bounded to 0-100 (null if duration is unknown). A movie with no saved position has inProgress: false and, when duration is known, progressPercent: 0, even if it was previously watched.

These fields are independent of watched: a movie can be both watched and in progress, for example during a rewatch. The watched and unwatched filters still use Plex's watched state, not saved progress. For cleanup, inspect inProgress as well as watched to avoid selecting movies with a saved playback position.

For TV libraries, watched=true includes partially watched shows with at least one played episode. A show's returned watched flag is true only when all its available episodes are played. watchStatus explicitly reports unwatched, partial, or watched, and watchedEpisodeCount gives the played count alongside episodeCount. Empty shows are reported as unwatched. For cleanup workflows, check watchStatus == "watched" before considering an entire show for deletion; the filter alone does not mean a show is complete.

unwatched=true uses Plex's unwatched filter; for shows, it can include partially watched series with episodes remaining. Do not set both filters to true.

Media Module

Tools for searching, inspecting, and editing specific media items.

library_get_contents and media_get_details accept username for a Home or shared user, using the configured admin credentials. Omit it for your account. Watched filters and saved playback progress belong to the selected user; failed access returns an error. Movie, episode and track details include watched, view_count, playback_offset_ms, in_progress, and progress_percent.

Watchlist Module

Manage the Plex account Watchlist, including movies and shows outside your library.

Search first, then pass the chosen result's guid to watchlist_add. To remove an entry, use its GUID from watchlist_list. These plex://movie/... or plex://show/... identifiers are cloud IDs, not local media_id/ratingKey values. List results default to 50 items; increase offset for the next page.

All four tools use the configured PLEX_TOKEN. Pass username to select a user by exact username or profile title, or home_user_id to select by ID (takes precedence). Supply pin if Plex requires it. If Plex cannot access that user's Watchlist, the tool returns an error without falling back to your Watchlist. Omit the selectors to use the configured account. Add/remove operations confirm membership and leave media files and watched status unchanged.

Playlist Module

Manage your personal and shared playlists.

Pass username to work with a Home or shared user's playlists using the configured admin credentials. Omit it to use the configured account. Failed access returns an error. For playlist_copy_to_user, username is the destination; source_username selects the source account and defaults to the configured account.

Collection Module

Organize movies and shows into collections.

User Module

Information about the server owner and shared users.

user_get_continue_watching accepts an exact username/profile title or a user_id from user_list_all_users. The ID takes precedence; omit both for the configured account. Access to other users requires the server administrator's token and is limited to this Plex server. Failed access returns an error.

Sessions Module

Monitor real-time server activity.

Server Module

Maintenance and administrative tools.

Client Module

Control playback and navigation on Plex clients.

Response Formats

All tools return information in JSON format for consistent parsing.

Success Example

{
  "status": "success",
  "data": {
    "title": "Inception",
    "year": 2010,
    "rating": 8.8
  }
}

Error Example

{
  "status": "error",
  "message": "Library 'Missing' not found."
}

Multiple Matches

If an operation finds multiple items with the same name, it returns a list of specific identifiers:

[
  {
    "title": "The Office",
    "id": 123,
    "type": "show",
    "year": 2005
  },
  {
    "title": "The Office",
    "id": 456,
    "type": "show",
    "year": 1995
  }
]

Troubleshooting OAuth

• 401 Unauthorized: Ensure your MCP_OAUTH_ISSUER exactly matches the issuer URL in your identity provider (including trailing slashes). If MCP_OAUTH_AUDIENCE is set, it must equal the client ID your provider puts in the token's aud claim.
• Public URL: MCP_SERVER_URL must be reachable by the client (e.g., plexmcp.example.com) and should use HTTPS.
• Redirect URI mismatch (provider error page after login): the client's callback isn't in the provider's redirect list — see the table in step 1. Use the exact callback requested by the client. For Codex, replace <callback-id> in the example with the actual callback ID; only the loopback port should vary.
• Client hangs after login / "Couldn't connect": check the server log for Token valid vs Token validation failed. A failure right after a successful /token usually means MCP_OAUTH_AUDIENCE doesn't match the token's aud — unset it to confirm, then set it to the Client ID.
• First request slow: token validation caches discovery metadata until restart and caches JWKS for MCP_OAUTH_JWKS_CACHE_TTL seconds (default 3600). After rotating signing keys in the provider, restart the server or wait for the cache to expire.