Skip to content
Back to search

plex-mcp-server

MCP Server for Plex to allow LLMs to converse with Plex.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vladimir-tutin--plex-mcp-server/badge.svg)](/listings/vladimir-tutin--plex-mcp-server)

HTML

<a href="/listings/vladimir-tutin--plex-mcp-server"><img src="/api/listings/vladimir-tutin--plex-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 665 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Plex MCP Server
  2. An MCP server for managing Plex libraries, media, and playback from Claude, ChatGPT, and other MCP clients.
  3. ## Features
  4. - **JSON responses**: Structured results for Plex operations.
  5. - **Multiple Transports**: Supports `stdio`, SSE (Server-Sent Events), and Streamable HTTP.
  6. - **Comprehensive Control**: Manage libraries, media, collections, playlists, clients, and users.
  7. - **Remote Ready**: Built-in OAuth 2.1 support for integration with remote AI platforms like Claude.ai.
  8. - **Admin Tools**: Access logs, monitor bandwidth, and run Butler tasks.
  9. ## Installation
  10. ### Option 1: Using uv (Recommended)
  11. Run directly without installation:
  12. ```bash
  13. uvx plex-mcp-server --transport stdio --plex-url http://your-server:32400 --plex-token your-token
  14. ```
  15. ### Option 2: Install via pip
  16. ```bash
  17. pip install plex-mcp-server
  18. ```
  19. ### Option 3: Development / Source
  20. ```bash
  21. git clone https://github.com/vladimir-tutin/plex-mcp-server.git
  22. cd plex-mcp-server
  23. pip install -e .
  24. ```
  25. ### Option 4: Docker
  26. The published image is `ghcr.io/vladimir-tutin/plex-mcp-server:latest` for Linux
  27. amd64 and arm64. It runs as a non-root user and serves Streamable HTTP at `/mcp`
  28. and legacy SSE at `/sse`. No media folders need to be mounted: it uses Plex's API.
  29. Follow the Docker setup below, then see
  30. [Public HTTPS access](#public-https-access) for hosted clients such as Claude.ai or ChatGPT.
  31. #### Docker Compose
  32. ```bash
  33. git clone https://github.com/vladimir-tutin/plex-mcp-server.git
  34. cd plex-mcp-server
  35. cp .env.docker.example .env
  36. ```
  37. Edit `.env` before starting. For a trusted LAN deployment, for example:
  38. ```env
  39. PLEX_URL=http://192.168.1.10:32400
  40. PLEX_TOKEN=your-plex-token
  41. MCP_BIND_ADDRESS=192.168.1.20
  42. MCP_PUBLISHED_PORT=3001
  43. MCP_SERVER_URL=http://192.168.1.20:3001
  44. MCP_OAUTH_ENABLED=false
  45. ```
  46. Replace `192.168.1.10` with the Plex address and `192.168.1.20` with the Docker
  47. host's address. Without OAuth, anyone who can reach this port can use the tools.
  48. The supplied example file defaults to loopback (`127.0.0.1`) instead, for access
  49. from the Docker host only. Keep `.env` private.
  50. ```bash
  51. docker compose pull
  52. docker compose up -d --no-build
  53. docker compose logs -f
  54. ```
  55. The LAN example's client URL is `http://192.168.1.20:3001/mcp`. Hosted clients
  56. need a reachable HTTPS endpoint; follow [Public HTTPS access](#public-https-access).
  57. #### Other Docker deployments
  58. Use `ghcr.io/vladimir-tutin/plex-mcp-server:latest`, publish container port
  59. `3001` (TCP), and set these environment variables:
  60. | Key | Example value |
  61. |---|---|
  62. | `PLEX_URL` | `http://192.168.1.10:32400` |
  63. | `PLEX_TOKEN` | `your-plex-token` |
  64. | `MCP_SERVER_URL` | `http://192.168.1.20:3001` |
  65. | `MCP_TRANSPORT` | `streamable-http` (default; serves both `/mcp` and `/sse`) |
  66. Use your Docker host's address and published port in `MCP_SERVER_URL`.
  67. `MCP_BIND_ADDRESS` and `MCP_PUBLISHED_PORT` only configure this repository's
  68. Compose file; for other deployments, set the port mapping directly.
  69. #### Public HTTPS access
  70. Setting `MCP_SERVER_URL` does **not** create DNS records, configure HTTPS, or
  71. publish the container. Complete these steps before connecting a hosted client:
  72. 1. Create an OAuth provider using [Remote Access & OAuth](#remote-access--oauth).
  73. 2. Set these values in Compose's `.env` or your container's environment:
  74. ```env
  75. MCP_SERVER_URL=https://plexmcp.example.com
  76. MCP_OAUTH_ENABLED=true
  77. MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
  78. MCP_OAUTH_AUDIENCE=your-oauth-client-id
  79. ```
  80. Keep `PLEX_URL` and `PLEX_TOKEN` set as above. These are separate from your
  81. OAuth credentials. `MCP_SERVER_URL` is the public **base URL**, without `/mcp`
  82. or `/sse`. `MCP_OAUTH_ISSUER` is the provider's exact issuer URL,
  83. including its path and trailing slash.
  84. 3. Point the public hostname at your reverse proxy and configure a valid HTTPS
  85. certificate. Forward that hostname to the MCP container's published address,
  86. for example `http://192.168.1.20:3001`. This is the Docker host and
  87. **host port**, not Plex's port `32400` or Authentik's address.
  88. 4. Forward all paths on that hostname unchanged, preserve the public `Host` and
  89. `Authorization` headers, and allow streaming responses without buffering.
  90. With Compose, the published address must be reachable by the proxy: use the
  91. Docker host's LAN address when the proxy runs elsewhere. A proxy in another
  92. container cannot reach this container through its own `127.0.0.1`.
  93. 5. Let requests reach the MCP server's OAuth middleware rather than intercepting
  94. them with a browser-login page at the proxy. This includes `/mcp`, `/sse`,
  95. `/messages/`, `/.well-known/` discovery paths, `/authorize`, and `/token`.
  96. The MCP server validates bearer tokens; Authentik handles the OAuth login.
  97. 6. Recreate the container with the updated settings (`docker compose up -d --no-build`
  98. for Compose). Configure clients with `https://plexmcp.example.com/mcp` (Streamable HTTP)
  99. or `https://plexmcp.example.com/sse` (legacy SSE).
  100. With OAuth enabled, an unauthenticated request to `/mcp` or `/sse` should return
  101. **401**, while `/.well-known/oauth-protected-resource` should return JSON. A proxy
  102. login page or a 502 indicates the request is not reaching the expected MCP handler.
  103. Finish by signing in from your client and asking it to list your Plex libraries.
  104. When moving an existing deployment, update the reverse proxy's upstream to the
  105. new host and port. You can retain the public MCP URL and client URLs. If the OAuth
  106. provider also moves, preserve its issuer URL and configuration or update
  107. `MCP_OAUTH_ISSUER` and the client credentials to match.
  108. #### Updating or building the image
  109. `latest` tracks published releases; `edge` tracks main. Use a version tag such as
  110. `1.2.0` to pin a release. Running containers do not update automatically.
  111. For Compose, update with:
  112. ```bash
  113. docker compose pull
  114. docker compose up -d --no-build
  115. ```
  116. To build from source, run `docker compose build --pull`, then
  117. `docker compose up -d --no-build`.
  118. To run the published image without Compose, prepare `.env` with the server
  119. variables above and choose the host binding explicitly:
  120. ```bash
  121. docker run -d --name plex-mcp-server --restart unless-stopped --init \
  122. --env-file .env -p 127.0.0.1:3001:3001 ghcr.io/vladimir-tutin/plex-mcp-server:latest
  123. ```
  124. This command publishes on loopback only. For standalone SSE, append
  125. `--transport sse --host 0.0.0.0 --port 3001`. For stdio, use
  126. `docker run --rm -i --env-file .env ghcr.io/vladimir-tutin/plex-mcp-server:latest --transport stdio`
  127. without publishing a port.
  128. ## Configuration
  129. For containers, use the [Docker setup](#option-4-docker). The following options also
  130. apply to direct Python installations. `PLEX_URL` points to Plex; `MCP_SERVER_URL`
  131. is the address of this MCP service. Inside a container, `localhost` refers to the
  132. container itself, so use a reachable network address for Plex.
  133. Set your Plex server URL and Token using one of these methods:
  134. ### 1. Command Line Arguments
  135. ```bash
  136. plex-mcp-server --plex-url "http://192.168.1.10:32400" --plex-token "ABC123XYZ"
  137. ```
  138. ### 2. Environment Variables (.env)
  139. Create a `.env` file in the current directory or `~/.config/plex-mcp-server/.env`:
  140. ```env
  141. PLEX_URL=http://localhost:32400
  142. PLEX_TOKEN=your-authentication-token
  143. MCP_OAUTH_ENABLED=false
  144. ```
  145. For OAuth settings, see [Remote Access & OAuth](#remote-access--oauth).
  146. ### 3. MCP Client Config
  147. Example for Claude Desktop (`%APPDATA%/Claude/claude_desktop_config.json`):
  148. ```json
  149. {
  150. "mcpServers": {
  151. "plex": {
  152. "command": "uvx",
  153. "args": [
  154. "plex-mcp-server",
  155. "--transport",
  156. "stdio",
  157. "--plex-url",
  158. "http://your-server:32400",
  159. "--plex-token",
  160. "your-token"
  161. ]
  162. }
  163. }
  164. }
  165. ```
  166. #### Remote servers from stdio-only clients
  167. If your client only supports launching a local stdio process, use
  168. [`mcp-remote`](https://github.com/geelen/mcp-remote) to connect it to a remote Plex MCP
  169. server. Install Node.js (which provides `npx`) on the client machine, then use:
  170. ```json
  171. {
  172. "mcpServers": {
  173. "plex": {
  174. "command": "npx",
  175. "args": ["-y", "mcp-remote", "https://plexmcp.example.com/mcp"]
  176. }
  177. }
  178. }
  179. ```
  180. Use `/mcp` when the server runs with `--transport streamable-http`. For an SSE
  181. deployment, use `/sse` instead. For plain HTTP on a trusted private network, append
  182. `"--allow-http"` to the arguments. If OAuth is enabled, follow the bridge's
  183. [OAuth configuration instructions](https://github.com/geelen/mcp-remote#readme),
  184. including any required client credentials and callback registration.
  185. Clients with native remote HTTP support can connect directly to `/mcp` and do not
  186. need Node.js, `npx`, or this bridge. The local stdio setup above also needs no bridge.
  187. ### 4. Claude Connector Installation
  188. Go to https://claude.ai/settings/connectors and add a new connector with the following settings:
  189. - Name: Plex MCP
  190. - URL: `https://plexmcp.example.com/sse` for SSE, or `https://plexmcp.example.com/mcp` when running with `--transport streamable-http`.
  191. - If OAuth is enabled, enter your provider's Client ID and Client Secret in the advanced settings and complete sign-in.
  192. Register Claude's callback in your OAuth provider: `https://claude.ai/api/mcp/auth_callback`.
  193. See [Remote Access & OAuth](#remote-access--oauth) for provider and reverse-proxy configuration.
  194. <img width="516" height="515" alt="image" src="https://github.com/user-attachments/assets/7949a127-51a7-4c60-a121-511ee4a1f00d" />
  195. ### 5. ChatGPT Connector Installation
  196. Start the server with `--transport streamable-http` and make it reachable at a public HTTPS URL.
  197. In ChatGPT's plugin settings, choose **Add custom MCP server**:
  198. - Name: Plex MCP
  199. - Server URL: `https://plexmcp.example.com/mcp`
  200. - Authentication: **OAuth** if enabled on the server; otherwise **None**.
  201. - 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.
  202. ![ChatGPT custom MCP server form with Advanced OAuth settings expanded](docs/images/chatgpt-oauth-settings.png)
  203. The screenshot shows where to find the OAuth settings if your server requires them.
  204. It uses a placeholder server URL, so discovery fails in this example. Use your real
  205. server URL and the token endpoint authentication method required by your provider.
  206. Register the exact ChatGPT callback URL with your OAuth provider. It can look like
  207. `https://chatgpt.com/connector/oauth/<callback-id>`; use the value requested by your
  208. connection, not the literal placeholder. Create the plugin, complete sign-in, and
  209. refresh its tools. Test it by asking ChatGPT to list your Plex libraries.
  210. For reverse-proxy routing, see [Public HTTPS access](#public-https-access).
  211. The website plugin and a local Codex MCP entry are separate connections. For local
  212. Codex OAuth configuration, see the [client setup instructions](#3-configure-each-client).
  213. ## Streamable HTTP
  214. Start the server with `--transport streamable-http` to expose `/mcp`:
  215. ```bash
  216. plex-mcp-server --transport streamable-http --port 3001 --server-url https://plexmcp.example.com
  217. ```
  218. Configure your client with `https://plexmcp.example.com/mcp`. This mode also keeps
  219. the legacy `/sse` and `/messages/` endpoints available for existing clients.
  220. Set `MCP_TRANSPORT` in `.env` or your container's environment to select
  221. `streamable-http`, `sse`, or `stdio`. An explicit `--transport` flag overrides it.
  222. Docker defaults to `streamable-http`, serving both `/mcp` and legacy `/sse`.
  223. Direct execution defaults to `sse` when neither the variable nor flag is supplied.
  224. For Docker stdio, the MCP client must launch the container with `docker run --rm -i`;
  225. no port mapping is needed.
  226. OAuth is optional on both HTTP transports. Enable it with `--oauth-enabled` or
  227. `MCP_OAUTH_ENABLED=true`, using the issuer settings below. Without OAuth, anyone
  228. who can reach the endpoints can call the tools; use an appropriate network boundary.
  229. Both SSE and Streamable HTTP validate Host and Origin headers to block DNS-rebinding
  230. attacks (a malicious web page driving your server through your browser). `--server-url`
  231. (or `MCP_SERVER_URL`) permits your public hostname and origin even with OAuth disabled.
  232. For additional proxy names, LAN addresses, or browser origins, set comma-separated
  233. `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` (e.g. `MCP_ALLOWED_HOSTS=192.168.1.20:3001`).
  234. Loopback hosts are allowed by default. If a remote client gets `421 Invalid Host header`,
  235. add its host and port to `MCP_ALLOWED_HOSTS`. For a rejected browser origin,
  236. add the full origin (scheme, host, and port) to `MCP_ALLOWED_ORIGINS`.
  237. ## Remote Access & OAuth
  238. OAuth protects both HTTP transports. The following setup uses Authentik as the identity provider.
  239. ### How it works
  240. The MCP server acts as the OAuth front door: clients discover it via
  241. `/.well-known/oauth-protected-resource`, are sent to `/authorize` (which redirects to
  242. your identity provider), and exchange codes at `/token` (which the server proxies to the
  243. provider). Clients therefore only ever need **your MCP server URL** plus the provider's
  244. Client ID / Secret. The browser visits the provider to complete sign-in. Access tokens are JWTs
  245. validated against the provider's JWKS; the server checks signature, expiry, issuer, and
  246. (optionally) audience on every request, on both SSE and Streamable HTTP.
  247. ### 1. Create an OAuth provider (Authentik example)
  248. 1. **Providers → Create → OAuth2/OpenID Provider.** Client type *Confidential*, signing
  249. key set (RS256). Note the **Client ID** and **Client Secret**.
  250. 2. **Redirect URIs** — add one entry per client you plan to use. These are the values
  251. seen in practice:
  252. | Client | Redirect URI |
  253. |---|---|
  254. | Claude.ai / Claude Desktop | `https://claude.ai/api/mcp/auth_callback` |
  255. | ChatGPT connector | `https://chatgpt.com/connector/oauth/<connector-id>` — shown in the connector dialog |
  256. | Codex CLI / local tools | loopback, random port: regex `^http://127\.0\.0\.1:[0-9]+/callback/<callback-id>$` |
  257. Keep this list tight. A catch-all like `.*` lets anyone who can get you to click a
  258. link capture an authorization code.
  259. 3. **Applications → Create**, bind it to the provider, and **bind an access policy**
  260. (your user or group). Any Authentik user who can authorize this application gets full
  261. control of Plex — there are no per-user roles inside the MCP server.
  262. 4. Copy the provider's **OpenID Configuration Issuer** URL, e.g.
  263. `https://auth.example.com/application/o/plexmcp-oauth/` (trailing slash included).
  264. ### 2. Configure the server
  265. For Docker, enter these as environment variables using the
  266. [public HTTPS setup](#public-https-access), which also covers DNS and the reverse proxy.
  267. ```env
  268. MCP_OAUTH_ENABLED=true
  269. MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
  270. MCP_SERVER_URL=https://plexmcp.example.com
  271. MCP_OAUTH_AUDIENCE=<Client ID> # optional, recommended
  272. ```
  273. or the equivalent flags: `--oauth-enabled --oauth-issuer … --server-url … --oauth-audience …`.
  274. - `MCP_SERVER_URL` must be the public HTTPS URL clients reach; it also becomes the
  275. allowed Host/Origin for DNS-rebinding protection. Use the base URL without `/mcp`
  276. or `/sse`; HTTPS is provided by your reverse proxy.
  277. - `MCP_OAUTH_AUDIENCE` makes the server reject tokens minted for any *other* client of
  278. the same provider. Set it to the Client ID from step 1. Leaving it unset disables audience validation for compatibility with existing deployments.
  279. ### 3. Configure each client
  280. Use the Client ID and Secret from step 1 and one of these URLs:
  281. | Client | URL | Notes |
  282. |---|---|---|
  283. | Claude.ai / Claude Desktop | `https://plexmcp.example.com/sse` | Claude probes with a Streamable HTTP POST first and falls back to SSE automatically |
  284. | ChatGPT | `https://plexmcp.example.com/mcp` | Authentication: OAuth, paste Client ID/Secret |
  285. | Codex CLI | `codex mcp add plex --url https://plexmcp.example.com/mcp --oauth-client-id <id> --oauth-client-secret <secret>` | opens a browser for login |
  286. Clients configured with `/mcp` use Streamable HTTP; `/sse` uses the legacy transport.
  287. Both are protected identically.
  288. ### Discovery Endpoints
  289. When OAuth is active, the following standard endpoints are exposed without
  290. authentication:
  291. - `/.well-known/oauth-protected-resource`
  292. - `/.well-known/oauth-authorization-server`
  293. - `/authorize` (redirects to the provider) and `/token` (proxied to the provider)
  294. ## Command Reference
  295. ### Library Module
  296. Tools for exploring and managing your Plex libraries.
  297. | Command | Description | Parameters |
  298. |---------|-------------|------------|
  299. | `library_list` | Lists all available libraries. | None |
  300. | `library_get_stats` | Gets statistics (count, size, types) for a library. | `library_name` |
  301. | `library_refresh` | Triggers a metadata refresh for a library. | `library_name` |
  302. | `library_scan` | Scans a library for new files. | `library_name` |
  303. | `library_get_details` | Gets detailed information about a library. | `library_name` |
  304. | `library_get_recently_added` | Lists recently added items in a library. | `library_name`, `limit: int` |
  305. | `library_get_contents` | Lists current library items with media IDs, filters, and pagination. | `library_name` (optional), `media_type`, `watched: bool`, `unwatched: bool`, `offset: int`, `limit: int`, `sort`, `title`, `genre`, `year`, `content_rating`, `director`, `actor`, `writer`, `resolution`, `network`, `studio`, `username` |
  306. To list watched movies currently in your library (rather than playback history):
  307. ```json
  308. {"library_name": "Movies", "watched": true, "offset": 0, "limit": 50}
  309. ```
  310. Each result includes `media_id` (Plex's `ratingKey`) for looking up or deleting that
  311. specific item. The default page size is 50; increase `offset` to retrieve later pages.
  312. `totalItems` is the count matching the server-side filters, not just the current page.
  313. Use `title` to combine a case-insensitive Plex title search with other filters:
  314. `{"library_name":"Movies","title":"Avengers","watched":true}`.
  315. This returns all matches with normal pagination. It is not exact-only or arbitrary
  316. substring matching: `Avengers` matches titles containing that word, while `venger`
  317. does not. Title searches use the selected media type; TV libraries default to show names.
  318. Watch state belongs to the selected `username`, or the configured account when omitted.
  319. To search across all accessible libraries, omit `library_name` and supply `media_type`:
  320. ```json
  321. {"media_type":"movie","watched":true,"genre":"Action"}
  322. ```
  323. Supported types are `movie`, `show`, `episode`, `artist`, `album`, and `track`.
  324. You can also select a type within a named library, such as `episode` in a TV library
  325. or `track` in a music library. Type-selected results include the originating `library`
  326. and `library_id`; episodes include their show/season/episode and tracks their artist/album.
  327. Filters and sorting apply before pagination across the combined results. At least
  328. one of `library_name` or `media_type` is required. Broad episode queries can be slower
  329. on large libraries; a library or title filter narrows the search.
  330. For music, `watched`/`unwatched` select played/unplayed items. Artist and album played
  331. state does not imply every track is complete.
  332. Movie, episode, and track results also include `inProgress` and `progressPercent`, based on Plex's
  333. saved playback offset, even if the movie is absent from Continue Watching.
  334. `inProgress` is true when that offset is positive; it does not mean the movie is
  335. currently playing. `progressPercent` is the saved position as a percentage of
  336. duration, rounded to one decimal and bounded to 0-100 (null if duration is unknown).
  337. A movie with no saved position has `inProgress: false` and, when duration is known,
  338. `progressPercent: 0`, even if it was previously watched.
  339. These fields are independent of `watched`: a movie can be both watched and in
  340. progress, for example during a rewatch. The `watched` and `unwatched` filters still
  341. use Plex's watched state, not saved progress. For cleanup, inspect `inProgress`
  342. as well as `watched` to avoid selecting movies with a saved playback position.
  343. For shows, `watched=true` selects series with no unwatched episodes;
  344. `unwatched=true` selects those with episodes remaining, including partially watched
  345. series. Results include `watchStatus` (`unwatched`, `partial`, or `watched`),
  346. `watchedEpisodeCount`, and `episodeCount`. Completion refers to episodes currently
  347. in the library, not future or missing episodes. Empty shows report `watched=false`.
  348. Do not set both filters to true.
  349. Filters must apply to the selected media type; unsupported combinations return an
  350. error rather than being silently ignored. Episode genre, rating, people, network,
  351. and studio filters use the parent show. Track year and studio use the parent album.
  352. Artist filters support title and genre; albums and tracks also support year and studio.
  353. Resolution applies to movies and episodes (`sd`, `480`, `576`, `720`, `1080`, `2k`,
  354. `4k`, or `8k`).
  355. ### Media Module
  356. Tools for searching, inspecting, and editing specific media items.
  357. | Command | Description | Parameters |
  358. |---------|-------------|------------|
  359. | `media_search` | Search for media across all libraries. | `query`, `library_name`, `content_type` |
  360. | `media_get_details` | Get comprehensive details for an item. | `media_title`, `library_name`, `media_id`, `username` |
  361. | `media_set_watched_status` | Mark an item watched or unwatched. Shows, seasons, albums and artists apply to every episode or track, including partly watched ones. | `media_id`, `watched`, `username` |
  362. | `media_edit_metadata` | Update tags, genres, summary, or title. | `media_title`, `library_name`, `new_title`, `new_summary`, `new_rating`, `new_release_date`, `new_genre`, `remove_genre`, `new_director`, `new_studio`, `new_tags` |
  363. | `media_delete` | Remove an item from Plex. | `media_title`, `library_name`, `media_id`, `username` |
  364. | `media_get_artwork` | Retrieve posters or background artwork. | `media_title`, `library_name`, `art_type: str` |
  365. | `media_set_artwork` | Set artwork from a local path or URL. | `media_title`, `library_name`, `poster_path`, `poster_url`, `background_path`, `background_url` |
  366. | `media_list_available_artwork` | List alternative artwork available for selection. | `media_title`, `library_name`, `art_type` |
  367. `library_get_contents`, `media_get_details` and `media_set_watched_status` accept
  368. `username` for a Home or shared user, using the configured admin credentials. Omit it
  369. for your account.
  370. Watched filters and saved playback progress belong to the selected user; failed
  371. access returns an error. Movie, episode and track details include `watched`,
  372. `view_count`, `playback_offset_ms`, `in_progress`, and `progress_percent`. Show,
  373. season, album and artist details include `watched`, `watch_status` (`watched`, `partial` or
  374. `unwatched`), `watched_count`, and `total_count`.
  375. ### Watchlist Module
  376. Manage the Plex account Watchlist, including movies and shows outside your library.
  377. Listings and search results include `release_date`, `duration_ms` (runtime in
  378. milliseconds), and `content_rating` when Plex supplies them, without extra lookups.
  379. The release date does not distinguish theatrical, physical, or streaming releases.
  380. By default, listing also looks up the selected user's library state. Movies include saved
  381. progress and watched status; shows include watched and total episode counts. Matching
  382. uses Plex GUIDs first, then searches by title and verifies shared IMDb, TMDB, or TVDB
  383. IDs. Each matching library copy is returned in `library_items`. Unmatched items have
  384. unknown availability (`null`), not an unwatched state. Lookup failures leave the
  385. Watchlist available with a `state_error`. Set `include_state=false` to skip library
  386. lookups. Individual episode progress is not included.
  387. | Command | Description | Parameters |
  388. |---|---|---|
  389. | `watchlist_list` | List Watchlist titles with local availability and watched/progress state. | `offset`, `limit` (1–100), `include_state` (default `true`) |
  390. | `watchlist_search` | Search Plex Discover for titles to add. | `query`, `content_type` (movie/show), `limit` (1–100) |
  391. | `watchlist_add` | Add a movie or show. | `guid` |
  392. | `watchlist_remove` | Remove a movie or show. | `guid` |
  393. Search first, then pass the chosen result's `guid` to `watchlist_add`. To remove
  394. an entry, use its GUID from `watchlist_list`. These `plex://movie/...` or
  395. `plex://show/...` identifiers are cloud IDs, not local `media_id`/`ratingKey` values.
  396. List results default to 50 items; increase `offset` for the next page.
  397. All four tools use the configured `PLEX_TOKEN`. Pass `username` to select a user
  398. by exact username or profile title, or `home_user_id` to select by ID (takes
  399. precedence). Supply `pin` if Plex requires it. If Plex cannot access that user's
  400. Watchlist, the tool returns an error without falling back to your Watchlist.
  401. Omit the selectors to use the configured account.
  402. Add/remove operations confirm membership and leave media files and watched status unchanged.
  403. ### Playlist Module
  404. Manage your personal and shared playlists.
  405. | Command | Description | Parameters |
  406. |---------|-------------|------------|
  407. | `playlist_list` | List playlists. | `library_name`, `content_type`, `username` |
  408. | `playlist_get_contents` | List playlist items. | `playlist_title`, `playlist_id`, `username` |
  409. | `playlist_create` | Create a playlist. | `playlist_title`, `item_titles`, `library_name`, `summary`, `username` |
  410. | `playlist_delete` | Delete a playlist. | `playlist_title`, `playlist_id`, `username` |
  411. | `playlist_add_to` | Add media items. | `playlist_title`, `playlist_id`, `item_titles`, `item_ids`, `username` |
  412. | `playlist_remove_from` | Remove playlist items. | `playlist_title`, `playlist_id`, `item_titles`, `username` |
  413. | `playlist_edit` | Change title or summary. | `playlist_title`, `playlist_id`, `new_title`, `new_summary`, `username` |
  414. | `playlist_upload_poster` | Upload a poster. | `playlist_title`, `playlist_id`, `poster_url`, `poster_filepath`, `username` |
  415. | `playlist_copy_to_user` | Copy a playlist to another user. | `playlist_title`, `playlist_id`, `username`, `source_username` |
  416. Pass `username` to work with a Home or shared user's playlists using the configured
  417. admin credentials. Omit it to use the configured account. Failed access returns an
  418. error. For `playlist_copy_to_user`, `username` is the destination; `source_username`
  419. selects the source account and defaults to the configured account.
  420. #### Smart playlists
  421. Smart playlists save library filters that Plex reapplies as your library changes.
  422. All three tools accept `username`, including Home and shared users.
  423. | Tool | Purpose |
  424. |---|---|
  425. | `playlist_get_smart_filter_options` | Discover fields, operators, sorting and field values for `library_name` and optional `libtype`. |
  426. | `playlist_create_smart` | Save `filters`, `sort`, `limit` and `libtype` as a playlist. |
  427. | `playlist_edit_smart_filters` | Update a playlist by ID or title, preserving omitted settings. |
  428. Use `libtype="show"` with `{"title": "Band of Brothers"}` to match the show.
  429. Use `libtype="episode"` to match episode titles. Show and artist searches produce
  430. playable episodes and tracks. Use the same `libtype` when discovering filters.
  431. Creation and editing return the saved `definition`, item count and up to 20 items.
  432. `playlist_get_contents` returns all current items and the saved definition.
  433. On edit, omitted values remain unchanged; `{}` clears filters, an empty sort string
  434. clears sorting, and `limit=0` removes the limit. `libtype` changes only when supplied.
  435. ### Collection Module
  436. Organize movies and shows into collections.
  437. | Command | Description | Parameters |
  438. |---------|-------------|------------|
  439. | `collection_list` | List collections in a specific library. | `library_name` |
  440. | `collection_create` | Create a new collection. | `library_name`, `title`, `items: List[str]` |
  441. | `collection_add_to` | Add items to an existing collection. | `library_name`, `collection_title`, `items: List[str]`, `collection_id` |
  442. | `collection_remove_from` | Remove items from a collection. | `library_name`, `collection_title`, `items: List[str]`, `collection_id` |
  443. | `collection_edit` | Edit collection metadata and settings. | `collection_title`, `collection_id`, `library_name`, `new_title`, `new_sort_title`, `new_summary`, `new_content_rating`, `new_labels`, `add_labels`, `remove_labels`, `poster_path`, `poster_url`, `background_path`, `background_url`, `new_advanced_settings` |
  444. | `collection_delete` | Delete a collection. | `collection_title`, `collection_id`, `library_name` |
  445. ### User Module
  446. Information about the server owner and shared users.
  447. | Command | Description | Parameters |
  448. |---------|-------------|------------|
  449. | `user_search_users` | Search for shared users. | `search_term` |
  450. | `user_list_all_users` | List all users with types and IDs. | None |
  451. | `user_get_info` | Detailed info for a specific user. | `username` |
  452. | `user_get_on_deck` | Get "On Deck" items for a user. | `username` |
  453. | `user_get_continue_watching` | Get partially watched items to resume. | `limit`, `username`, `user_id` |
  454. | `user_get_watch_history` | Retrieve personal watch history. | `username`, `limit`, `content_type`, `user_id` |
  455. | `user_get_statistics` | Watch progress and usage statistics. | `time_period`, `username` |
  456. `user_get_continue_watching` accepts an exact username/profile title or a `user_id`
  457. from `user_list_all_users`. The ID takes precedence; omit both for the configured
  458. account. Access to other users requires the server administrator's token and is
  459. limited to this Plex server. Failed access returns an error.
  460. ### Sessions Module
  461. Monitor real-time server activity.
  462. | Command | Description | Parameters |
  463. |---------|-------------|------------|
  464. | `sessions_get_active` | Get currently playing items and clients. | None |
  465. | `sessions_get_media_playback_history` | History for a specific media item. | `media_title`, `library_name`, `media_id`, `username` |
  466. ### Server Module
  467. Maintenance and administrative tools.
  468. | Command | Description | Parameters |
  469. |---------|-------------|------------|
  470. | `server_get_plex_logs` | Retrieve lines from Plex logs. | `num_lines`, `log_type`, `start_line`, `list_files`, `search_term` |
  471. | `server_get_info` | Basic server health and version info. | None |
  472. | `server_get_bandwidth`| Bandwidth usage statistics. | `timespan`, `lan` |
  473. | `server_get_current_resources` | CPU/Memory usage of the host/process. | None |
  474. | `server_get_butler_tasks` | List scheduled maintenance tasks. | None |
  475. | `server_get_alerts` | Listen for server notifications/alerts. | `timeout` |
  476. | `server_run_butler_task` | Manually trigger a Butler task. | `task_name` |
  477. | `server_empty_trash` | Empty trash for libraries. | `library_name` |
  478. | `server_optimize_database` | Run database optimization. | None |
  479. | `server_clean_bundles` | Clean up unused media bundles. | None |
  480. ### Client Module
  481. Control playback and navigation on Plex clients.
  482. | Command | Description | Parameters |
  483. |---------|-------------|------------|
  484. | `client_list` | List all available playback clients. | `include_details: bool`, `active_only: bool` |
  485. | `client_get_details` | Detailed info for a client. | `client_name`, `client_id` |
  486. | `client_get_timelines` | Current playback state/trackers. | `client_name`, `client_id` |
  487. | `client_start_playback` | Start playing a media item on a client. | `media_title`, `client_name`, `rating_key`, `offset`, `library_name`, `use_external_player` |
  488. | `client_control_playback` | Play, Pause, Stop, Seek, Skip. | `client_name`, `action`, `offset`, `client_id` |
  489. | `client_navigate` | Send remote control navigation commands. | `client_name`, `command`, `client_id` |
  490. | `client_set_streams` | Changes audio or subtitle tracks. | `client_name`, `audio_stream_id`, `subtitle_stream_id`, `client_id` |
  491. ## Response Formats
  492. All tools return information in JSON format for consistent parsing.
  493. ### Success Example
  494. ```json
  495. {
  496. "status": "success",
  497. "data": {
  498. "title": "Inception",
  499. "year": 2010,
  500. "rating": 8.8
  501. }
  502. }
  503. ```
  504. ### Error Example
  505. ```json
  506. {
  507. "status": "error",
  508. "message": "Library 'Missing' not found."
  509. }
  510. ```
  511. ### Multiple Matches
  512. If an operation finds multiple items with the same name, it returns a list of specific identifiers:
  513. ```json
  514. [
  515. {
  516. "title": "The Office",
  517. "id": 123,
  518. "type": "show",
  519. "year": 2005
  520. },
  521. {
  522. "title": "The Office",
  523. "id": 456,
  524. "type": "show",
  525. "year": 1995
  526. }
  527. ]
  528. ```
  529. ## Troubleshooting OAuth
  530. - **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.
  531. - **Public URL**: `MCP_SERVER_URL` must be reachable by the client (e.g., plexmcp.example.com) and should use HTTPS.
  532. - **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.
  533. - **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.
  534. - **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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.