Plex MCP Server

Plex MCP 服务

用于从 Claude、ChatGPT 和其他 MCP 客户端管理 Plex 媒体库、媒体和播放的 MCP 服务。

功能

• JSON 响应：为 Plex 操作提供结构化结果。
• 多种传输方式：支持 stdio、SSE（Server-Sent Events）和 Streamable HTTP。
• 全面控制：管理媒体库、媒体、合集、播放列表、客户端和用户。
• 适用于远程连接：内置 OAuth 2.1 支持，可与 Claude.ai 等远程 AI 平台集成。
• 管理工具：访问日志、监控带宽并运行 Butler 任务。

安装

选项 1：使用 uv（推荐）

无需安装，直接运行：

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

选项 2：通过 pip 安装

pip install plex-mcp-server

选项 3：开发／源码

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

选项 4：Docker

已发布的镜像为 ghcr.io/vladimir-tutin/plex-mcp-server:latest，适用于 Linux amd64 和 arm64。它以非 root 用户身份运行，并在 /mcp 提供 Streamable HTTP 服务， 在 /sse 提供旧版 SSE 服务。无需挂载媒体文件夹：它使用 Plex API。

按照以下 Docker 设置操作，然后参阅 公开 HTTPS 访问，了解 Claude.ai 或 ChatGPT 等托管客户端的配置方法。

Docker Compose

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

启动前编辑 .env。例如，对于受信任的局域网部署：

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

将 192.168.1.10 替换为 Plex 地址，将 192.168.1.20 替换为 Docker 主机的地址。未启用 OAuth 时，任何能够访问此端口的人都可以使用这些工具。 提供的示例文件默认使用环回地址（127.0.0.1），因此只能从 Docker 主机访问。 请妥善保管 .env 文件。

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

局域网示例的客户端 URL 为 http://192.168.1.20:3001/mcp。托管客户端 需要可访问的 HTTPS 端点；请参阅公开 HTTPS 访问。

其他 Docker 部署

使用 ghcr.io/vladimir-tutin/plex-mcp-server:latest，发布容器端口 3001（TCP），并设置以下环境变量：

键	示例值
PLEX_URL	http://192.168.1.10:32400
PLEX_TOKEN	your-plex-token
MCP_SERVER_URL	http://192.168.1.20:3001
MCP_TRANSPORT	streamable-http（默认值；同时提供 /mcp 和 /sse）

在 MCP_SERVER_URL 中使用 Docker 主机的地址和已发布的端口。 MCP_BIND_ADDRESS 和 MCP_PUBLISHED_PORT 仅用于配置此仓库的 Compose 文件；对于其他部署，请直接设置端口映射。

公共 HTTPS 访问

设置 MCP_SERVER_URL 不会创建 DNS 记录、配置 HTTPS 或发布容器。连接托管客户端前，请完成以下步骤：

1. 使用远程访问与 OAuth创建 OAuth 提供方。

2. 在 Compose 的 .env 或容器环境中设置以下值：

   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
   

   按照上文设置 PLEX_URL 和 PLEX_TOKEN。它们与 OAuth 凭据相互独立。MCP_SERVER_URL 是公共基础 URL，不带 /mcp 或 /sse。MCP_OAUTH_ISSUER 必须是提供方的准确发行者 URL，包括路径和末尾的斜杠。

3. 将公共主机名指向反向代理，并配置有效的 HTTPS 证书。将该主机名转发到 MCP 容器发布的地址，例如 http://192.168.1.20:3001。这是 Docker 主机和主机端口，不是 Plex 的端口 32400 或 Authentik 的地址。

4. 原样转发该主机名下的所有路径，保留公共 Host 和 Authorization 标头，并允许流式响应且不进行缓冲。使用 Compose 时，代理必须能够访问发布的地址：如果代理在其他位置运行，请使用 Docker 主机的 LAN 地址。另一个容器中的代理无法通过自身的 127.0.0.1 访问此容器。

5. 让请求到达 MCP 服务的 OAuth 中间件，不要在代理处拦截请求并显示浏览器登录页面。这包括 /mcp、/sse、/messages/、/.well-known/ 发现路径、/authorize 和 /token。MCP 服务会验证 bearer token；Authentik 负责处理 OAuth 登录。

6. 使用更新后的设置重新创建容器（Compose 使用 docker compose up -d --no-build）。将客户端配置为使用 https://plexmcp.example.com/mcp（Streamable HTTP）或 https://plexmcp.example.com/sse（旧版 SSE）。

启用 OAuth 后，对 /mcp 或 /sse 的未认证请求应返回 401，而 /.well-known/oauth-protected-resource 应返回 JSON。如果出现代理登录页面或 502，说明请求未到达预期的 MCP 处理程序。最后，从客户端登录并让它列出你的 Plex 媒体库。

迁移现有部署时，请将反向代理的上游更新为新的主机和端口。你可以保留公共 MCP URL 和客户端 URL。如果 OAuth 提供方也迁移了，请保留其发行者 URL 和配置，或者更新 MCP_OAUTH_ISSUER 和客户端凭据以保持一致。

更新或构建镜像

latest 跟踪已发布的版本；edge 跟踪 main。使用 1.2.0 等版本标签来固定版本。运行中的容器不会自动更新。

对于 Compose，使用以下命令更新：

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

要从源代码构建，请运行 docker compose build --pull，然后运行 docker compose up -d --no-build。

要在不使用 Compose 的情况下运行已发布的镜像，请使用上文的服务变量准备 .env，并明确选择主机绑定地址：

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

此命令仅在 loopback 接口上发布。要独立运行 SSE，请追加 --transport sse --host 0.0.0.0 --port 3001。对于 stdio，请使用 docker run --rm -i --env-file .env ghcr.io/vladimir-tutin/plex-mcp-server:latest --transport stdio 而不发布端口。

配置

对于容器，请使用 Docker 设置。以下选项也适用于直接安装 Python。PLEX_URL 指向 Plex；MCP_SERVER_URL 是此 MCP 服务的地址。在容器内部，localhost 指向容器自身，因此 Plex 应使用可访问的网络地址。

使用以下任一方式设置 Plex 服务器 URL 和令牌：

1. 命令行参数

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

2. 环境变量（.env）

在当前目录或 ~/.config/plex-mcp-server/.env 中创建 .env 文件：

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

OAuth 设置请参阅远程访问与 OAuth。

3. MCP 客户端配置

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"
      ]
    }
  }
}

仅支持 stdio 的客户端连接远程服务

如果你的客户端仅支持启动本地 stdio 进程，请使用 mcp-remote 将其连接到远程 Plex MCP 服务。在客户端计算机上安装 Node.js（它提供 npx），然后使用：

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

当服务使用 --transport streamable-http 运行时，请使用 /mcp。对于 SSE 部署，请改用 /sse。如果是在受信任的专用网络上使用纯 HTTP，请在参数中追加 "--allow-http"。如果已启用 OAuth，请按照桥接程序的 OAuth 配置说明操作， 包括所需的客户端凭据和回调注册。

支持原生远程 HTTP 的客户端可以直接连接到 /mcp，无需 Node.js、npx 或此桥接程序。 上述本地 stdio 设置同样不需要桥接程序。

4. Claude Connector 安装

前往 https://claude.ai/settings/connectors，并使用以下设置添加新的连接器：

• 名称：Plex MCP
• URL：SSE 使用 https://plexmcp.example.com/sse；使用 --transport streamable-http 运行时使用 https://plexmcp.example.com/mcp。
• 如果已启用 OAuth，请在高级设置中输入提供商的 Client ID 和 Client Secret，并完成登录。

在 OAuth 提供商中注册 Claude 的回调：https://claude.ai/api/mcp/auth_callback。 有关提供商和反向代理配置，请参阅远程访问和 OAuth。

5. ChatGPT Connector 安装

使用 --transport streamable-http 启动服务，并确保它可通过公开的 HTTPS URL 访问。 在 ChatGPT 的插件设置中，选择 添加自定义 MCP 服务：

• 名称：Plex MCP
• 服务 URL：https://plexmcp.example.com/mcp
• 身份验证：如果服务已启用，则选择 OAuth；否则选择 无。
• 对于机密 OAuth 客户端，请打开 高级 OAuth 设置，并填写提供商的 Client ID 和 Client Secret。这些凭据与 Plex 令牌不同。

截图展示了服务器需要 OAuth 时 OAuth 设置的位置。 示例使用的是占位服务 URL，因此无法在此示例中完成发现。请使用你的实际 服务 URL，以及提供商要求的令牌端点身份验证方法。

向 OAuth 提供商注册准确的 ChatGPT 回调 URL。它可能类似于 https://chatgpt.com/connector/oauth/<callback-id>；请使用连接过程中要求的值， 而不是字面上的占位符。创建插件、完成登录，然后刷新其工具。你可以让 ChatGPT 列出 Plex 媒体库来测试。

有关反向代理路由，请参阅公开 HTTPS 访问。

网站插件和本地 Codex MCP 条目是独立的连接。有关本地 Codex OAuth 配置，请参阅 客户端设置说明。

Streamable HTTP

使用 --transport streamable-http 启动服务，以开放 /mcp：

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

将客户端配置为使用 https://plexmcp.example.com/mcp。此模式也会保留旧版 /sse 和 /messages/ 端点，供现有客户端使用。 在 .env 或容器环境中设置 MCP_TRANSPORT，以选择 streamable-http、sse 或 stdio。显式指定的 --transport 标志优先级更高。 Docker 默认使用 streamable-http，同时提供 /mcp 和旧版 /sse。 如果未设置变量或标志，直接执行时默认使用 sse。 对于 Docker stdio，MCP 客户端必须使用 docker run --rm -i 启动容器；无需映射端口。

两种 HTTP 传输方式都可选用 OAuth。使用下文的颁发者设置，通过 --oauth-enabled 或 MCP_OAUTH_ENABLED=true 启用 OAuth。 如果未启用 OAuth，任何能够访问这些端点的人都可以调用工具；请使用适当的网络边界。

SSE 和 Streamable HTTP 都会验证 Host 和 Origin 标头，以阻止 DNS 重绑定攻击（恶意网页通过你的浏览器操控服务）。 即使未启用 OAuth，--server-url（或 MCP_SERVER_URL）也会允许你的公共主机名和来源。 如需允许其他代理名称、LAN 地址或浏览器来源，请设置以逗号分隔的 MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS（例如 MCP_ALLOWED_HOSTS=192.168.1.20:3001）。 默认允许环回主机。如果远程客户端收到 421 Invalid Host header，请将其主机和端口添加到 MCP_ALLOWED_HOSTS。 如果浏览器来源被拒绝，请将完整来源（协议、主机和端口）添加到 MCP_ALLOWED_ORIGINS。

远程访问与 OAuth

OAuth 可保护两种 HTTP 传输方式。以下设置以 Authentik 作为身份提供方。

工作原理

MCP 服务充当 OAuth 入口：客户端通过 /.well-known/oauth-protected-resource 发现服务，随后被转到 /authorize（该端点会重定向到你的身份提供方），再到 /token 交换授权码（服务会将请求代理到提供方）。 因此，客户端只需要你的 MCP 服务 URL以及提供方的 Client ID / Secret。浏览器会访问提供方以完成登录。访问令牌是 JWT，每次请求时，服务都会在 SSE 和 Streamable HTTP 两种传输方式下，根据提供方的 JWKS 验证令牌，并检查签名、过期时间、颁发者以及（可选的）受众。

1. 创建 OAuth 提供方（Authentik 示例）

1. Providers → Create → OAuth2/OpenID Provider。 客户端类型选 Confidential，签名密钥集设为 RS256。记下 Client ID 和 Client Secret。

2. Redirect URIs — 为计划使用的每个客户端添加一个条目。以下是实际使用的值：

   客户端	重定向 URI
   Claude.ai / Claude Desktop	https://claude.ai/api/mcp/auth_callback
   ChatGPT connector	https://chatgpt.com/connector/oauth/<connector-id> — 显示在连接器对话框中
   Codex CLI / 本地工具	环回地址，随机端口：正则表达式 ^http://127\.0\.0\.1:[0-9]+/callback/<callback-id>$

   请严格限制此列表。像 .* 这样的通配规则会让任何能诱使你点击链接的人截获授权码。

3. Applications → Create，将其绑定到提供方，并绑定访问策略 （你的用户或群组）。任何有权授权此应用的 Authentik 用户都可以完全控制 Plex — MCP 服务内部没有按用户划分的角色。

4. 复制提供方的 OpenID Configuration Issuer URL，例如 https://auth.example.com/application/o/plexmcp-oauth/（包含末尾斜杠）。

2. 配置服务

对于 Docker，请使用 公共 HTTPS 配置将这些值设为环境变量，其中也涵盖 DNS 和反向代理。

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

或使用等效标志：--oauth-enabled --oauth-issuer … --server-url … --oauth-audience …。

• MCP_SERVER_URL 必须是客户端访问的公共 HTTPS URL；它也会成为 DNS 重绑定保护允许的 Host/Origin。使用不带 /mcp 或 /sse 的基础 URL；HTTPS 由反向代理提供。
• MCP_OAUTH_AUDIENCE 会让服务拒绝为同一提供商的任何其他客户端签发的令牌。将其设为第 1 步中的 Client ID。留空则会禁用受众验证，以兼容现有部署。

3. 配置每个客户端

使用第 1 步中的 Client ID 和 Secret，以及以下其中一个 URL：

客户端	URL	备注
Claude.ai / Claude Desktop	https://plexmcp.example.com/sse	Claude 会先使用 Streamable HTTP POST 探测，随后自动回退到 SSE
ChatGPT	https://plexmcp.example.com/mcp	身份验证：OAuth，粘贴 Client ID/Secret
Codex CLI	codex mcp add plex --url https://plexmcp.example.com/mcp --oauth-client-id <id> --oauth-client-secret <secret>	会打开浏览器进行登录

配置为使用 /mcp 的客户端使用 Streamable HTTP；/sse 使用旧版传输方式。 两者都受到同等保护。

发现端点

启用 OAuth 后，以下标准端点无需身份验证即可访问：

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server
• /authorize（重定向到提供商）和 /token（代理到提供商）

命令参考

媒体库模块

用于浏览和管理 Plex 媒体库的工具。

命令	描述	参数
library_list	列出所有可用的媒体库。	无
library_get_stats	获取媒体库的统计信息（数量、大小、类型）。	library_name
library_refresh	触发媒体库的元数据刷新。	library_name
library_scan	扫描媒体库中的新文件。	library_name
library_get_details	获取媒体库的详细信息。	library_name
library_get_recently_added	列出媒体库中最近添加的项目。	library_name, limit: int
library_get_contents	列出媒体库中的当前项目，包含媒体 ID、筛选条件和分页信息。	library_name（可选）, media_type, watched: bool, unwatched: bool, offset: int, limit: int, sort, title, genre, year, content_rating, director, actor, writer, resolution, network, studio, username

要列出媒体库中当前已观看的电影（而非播放历史）：

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

每个结果都包含 media_id（Plex 的 ratingKey），可用于查找或删除对应的项目。默认页大小为 50；增大 offset 可获取后续页面。 totalItems 是符合服务端筛选条件的项目数量，而非仅当前页面的数量。 使用 title 可将不区分大小写的 Plex 标题搜索与其他筛选条件结合使用： {"library_name":"Movies","title":"Avengers","watched":true}。 这会通过常规分页返回所有匹配项。它不是仅精确匹配，也不是任意子串匹配：Avengers 会匹配包含该词的标题，而 venger 不会。标题搜索使用所选媒体类型；电视媒体库默认搜索剧集名称。 观看状态属于所选的 username；若未指定，则属于已配置的账户。

要跨所有可访问的媒体库搜索，请省略 library_name 并提供 media_type：

{"media_type":"movie","watched":true,"genre":"Action"}

支持的类型包括 movie、show、episode、artist、album 和 track。 你也可以在指定的媒体库中选择类型，例如，在电视节目媒体库中选择 episode， 或在音乐媒体库中选择 track。按类型选择的结果包含所属的 library 和 library_id；剧集结果包含所属节目、季和剧集信息，曲目结果包含所属艺人和专辑。 筛选和排序会在合并结果上分页之前应用。必须至少指定 library_name 或 media_type 之一。在大型媒体库中，范围较广的剧集查询可能较慢； 使用媒体库或标题筛选条件可以缩小搜索范围。

对于音乐，watched/unwatched 分别选择已播放/未播放的项目。艺人和专辑的已播放 状态不代表其每首曲目都已播放完毕。

电影、剧集和曲目结果还包含 inProgress 和 progressPercent，这两个字段基于 Plex 保存的播放位置，即使电影不在“继续观看”列表中也是如此。 当保存的播放位置大于零时，inProgress 为 true；这不表示电影 当前正在播放。progressPercent 是保存位置占时长的百分比，四舍五入到小数点后一位， 并限制在 0 至 100 之间（时长未知时为 null）。 没有保存播放位置的电影，其 inProgress: false；如果时长已知， 则 progressPercent: 0，即使该电影之前已观看过也是如此。

这些字段与 watched 相互独立：例如，重看时，电影可以同时处于已观看和播放中状态。 watched 和 unwatched 筛选条件仍使用 Plex 的已观看状态，而非保存的播放进度。 清理时，请同时检查 inProgress 和 watched，以免选中有保存播放位置的电影。

对于节目，watched=true 会选择没有未观看剧集的系列； unwatched=true 会选择仍有待观看剧集的系列，包括部分观看过的系列。 结果包含 watchStatus（unwatched、partial 或 watched）、 watchedEpisodeCount 和 episodeCount。完成状态仅针对媒体库中当前存在的剧集， 不包括未来或缺失的剧集。没有剧集的节目会报告 watched=false。 不要同时将两个筛选条件设为 true。

筛选条件必须适用于所选媒体类型；不支持的组合会返回错误，而不会被静默忽略。 剧集的类型、评分、人物、电视网和制片厂筛选条件使用所属节目的信息。 曲目的年份和制片厂筛选条件使用所属专辑的信息。 艺人筛选支持标题和类型；专辑和曲目筛选还支持年份和制片厂。 分辨率适用于电影和剧集（sd、480、576、720、1080、2k、 4k 或 8k）。

媒体模块

用于搜索、检查和编辑特定媒体项目的工具。

命令	描述	参数
media_search	搜索所有媒体库中的媒体。	query、library_name、content_type
media_get_details	获取项目的详细信息。	media_title、library_name、media_id、username
media_set_watched_status	将项目标记为已观看或未观看。对剧集、季、专辑和艺人进行操作时，会应用于所有剧集或曲目，包括部分观看过的项目。	media_id、watched、username
media_edit_metadata	更新标签、流派、简介或标题。	media_title、library_name、new_title、new_summary、new_rating、new_release_date、new_genre、remove_genre、new_director、new_studio、new_tags
media_delete	从 Plex 中移除项目。	media_title、library_name、media_id、username
media_get_artwork	获取海报或背景图片。	media_title、library_name、art_type: str
media_set_artwork	使用本地路径或 URL 设置图片。	media_title、library_name、poster_path、poster_url、background_path、background_url
media_list_available_artwork	列出可供选择的其他图片。	media_title、library_name、art_type

library_get_contents、media_get_details 和 media_set_watched_status 接受 username，用于家庭用户或共享用户，并使用已配置的管理员凭据。不填写该参数 则针对你的帐户。 观看状态筛选和已保存的播放进度属于所选用户；访问失败时会返回错误。电影、分集和曲目详情包含 watched、 view_count、playback_offset_ms、in_progress 和 progress_percent。剧集、季、专辑和艺人详情包含 watched、watch_status（watched、partial 或 unwatched）、watched_count 和 total_count。

Watchlist 模块

管理 Plex 账户的 Watchlist，包括媒体库以外的电影和剧集。 Plex 提供时，列表和搜索结果会包含 release_date、duration_ms（以毫秒为单位的片长） 和 content_rating，无需额外查询。 发行日期不会区分院线、实体介质或流媒体发行。

默认情况下，列出内容时也会查询所选用户的媒体库状态。电影会包含已保存的 观看进度和观看状态；剧集会包含已观看集数和总集数。匹配时会优先使用 Plex GUID， 然后按标题搜索，并验证是否有相同的 IMDb、TMDB 或 TVDB ID。每个匹配的媒体库副本都会返回在 library_items 中。 未匹配的项目可用性未知（null），并非未观看状态。查询失败时，Watchlist 仍可用， 但会返回 state_error。设置 include_state=false 可跳过媒体库查询。不包含单集观看进度。

命令	描述	参数
watchlist_list	列出 Watchlist 标题及本地可用性和观看／进度状态。	offset、limit（1–100）、include_state（默认 true）
watchlist_search	在 Plex Discover 中搜索要添加的标题。	query、content_type（movie/show）、limit（1–100）
watchlist_add	添加电影或剧集。	guid
watchlist_remove	移除电影或剧集。	guid

先搜索，然后将所选结果的 guid 传给 watchlist_add。要移除条目， 请使用 watchlist_list 中的 GUID。这些 plex://movie/... 或 plex://show/... 标识符是云端 ID，而非本地 media_id／ratingKey 值。 列表结果默认包含 50 个项目；增大 offset 可查看下一页。

这四种工具都会使用已配置的 PLEX_TOKEN。传入 username 可按精确用户名 或个人资料标题选择用户，传入 home_user_id 可按 ID 选择用户（优先级更高）。 如果 Plex 要求 PIN，请提供 pin。如果 Plex 无法访问该用户的 Watchlist， 工具会返回错误，不会回退到你的 Watchlist。 省略选择参数则使用已配置的账户。 添加／移除操作会确认成员关系，且不会更改媒体文件和观看状态。

Playlist 模块

管理个人和共享播放列表。

命令	描述	参数
playlist_list	列出播放列表。	library_name、content_type、username
playlist_get_contents	列出播放列表项目。	playlist_title、playlist_id、username
playlist_create	创建播放列表。	playlist_title、item_titles、library_name、summary、username
playlist_delete	删除播放列表。	playlist_title、playlist_id、username
playlist_add_to	添加媒体项目。	playlist_title、playlist_id、item_titles、item_ids、username
playlist_remove_from	移除播放列表项目。	playlist_title、playlist_id、item_titles、username
playlist_edit	更改标题或简介。	playlist_title、playlist_id、new_title、new_summary、username
playlist_upload_poster	上传海报。	playlist_title、playlist_id、poster_url、poster_filepath、username
playlist_copy_to_user	将播放列表复制给另一位用户。	playlist_title、playlist_id、username、source_username

传入 username，使用已配置的管理员凭据操作家庭用户或共享用户的播放列表。 省略该参数则使用已配置的账户。访问失败时会返回错误。对于 playlist_copy_to_user， username 是目标用户；source_username 用于选择源账户，默认使用已配置的账户。

智能播放列表

智能播放列表会保存媒体库筛选条件，并在媒体库发生变化时由 Plex 重新应用。 这三个工具都接受 username，包括家庭用户和共享用户。

工具	用途
playlist_get_smart_filter_options	查看 library_name 和可选的 libtype 对应的字段、运算符、排序方式及字段值。
playlist_create_smart	将 filters、sort、limit 和 libtype 保存为播放列表。
playlist_edit_smart_filters	按 ID 或标题更新播放列表，并保留未提供的设置。

使用 libtype="show" 和 {"title": "Band of Brothers"} 可匹配剧集。 使用 libtype="episode" 可匹配分集标题。搜索剧集和艺人会返回 可播放的分集和曲目。发现筛选条件时，请使用相同的 libtype。

创建和编辑操作会返回已保存的 definition、项目数以及最多 20 个项目。 playlist_get_contents 会返回所有当前项目和已保存的定义。 编辑时，未提供的值保持不变；{} 会清除筛选条件，空排序字符串 会清除排序，limit=0 会移除限制。仅在提供 libtype 时才会更改它。

收藏集模块

将电影和剧集整理到收藏集中。

命令	说明	参数
collection_list	列出指定媒体库中的收藏集。	library_name
collection_create	创建新的收藏集。	library_name、title、items: List[str]
collection_add_to	将项目添加到现有收藏集。	library_name、collection_title、items: List[str]、collection_id
collection_remove_from	从收藏集中移除项目。	library_name、collection_title、items: List[str]、collection_id
collection_edit	编辑收藏集的元数据和设置。	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
collection_delete	删除收藏集。	collection_title、collection_id、library_name

用户模块

服务器所有者和共享用户的信息。

命令	说明	参数
user_search_users	搜索共享用户。	search_term
user_list_all_users	列出所有用户及其类型和 ID。	无
user_get_info	获取特定用户的详细信息。	username
user_get_on_deck	获取用户的“即将播放”项目。	username
user_get_continue_watching	获取可继续观看的未看完项目。	limit、username、user_id
user_get_watch_history	获取个人观看历史记录。	username、limit、content_type、user_id
user_get_statistics	观看进度和使用统计信息。	time_period、username

user_get_continue_watching 接受完全匹配的用户名／个人资料标题，或来自 user_list_all_users 的 user_id。 ID 优先级更高；两者都省略时使用已配置的账户。访问其他用户的数据需要服务器管理员的令牌，且 仅限此 Plex 服务器。访问失败时会返回错误。

会话模块

监控服务器的实时活动。

命令	说明	参数
sessions_get_active	获取当前正在播放的项目和客户端。	无
sessions_get_media_playback_history	获取特定媒体项目的历史记录。	media_title、library_name、media_id、username

服务器模块

维护和管理工具。

命令	描述	参数
server_get_plex_logs	获取 Plex 日志中的行。	num_lines、log_type、start_line、list_files、search_term
server_get_info	服务器基本运行状况和版本信息。	无
server_get_bandwidth	带宽使用统计信息。	timespan、lan
server_get_current_resources	主机／进程的 CPU／内存使用情况。	无
server_get_butler_tasks	列出计划的维护任务。	无
server_get_alerts	监听服务器通知／警报。	timeout
server_run_butler_task	手动触发 Butler 任务。	task_name
server_empty_trash	清空媒体库的回收站。	library_name
server_optimize_database	运行数据库优化。	无
server_clean_bundles	清理未使用的媒体包。	无

客户端模块

控制 Plex 客户端上的播放和导航。

命令	描述	参数
client_list	列出所有可用的播放客户端。	include_details: bool、active_only: bool
client_get_details	获取客户端的详细信息。	client_name、client_id
client_get_timelines	获取当前播放状态／跟踪信息。	client_name、client_id
client_start_playback	在客户端上开始播放媒体项目。	media_title、client_name、rating_key、offset、library_name、use_external_player
client_control_playback	播放、暂停、停止、跳转、跳过。	client_name、action、offset、client_id
client_navigate	发送遥控导航命令。	client_name、command、client_id
client_set_streams	更改音频或字幕轨道。	client_name、audio_stream_id、subtitle_stream_id、client_id

响应格式

所有工具均以 JSON 格式返回信息，以便统一解析。

成功示例

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

错误示例

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

多个匹配项

如果某项操作找到多个同名项目，则会返回具体标识符列表：

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

OAuth 故障排查

• 401 Unauthorized：确保 MCP_OAUTH_ISSUER 与身份提供商中的颁发者 URL 完全一致（包括末尾的斜杠）。如果设置了 MCP_OAUTH_AUDIENCE，其值必须与提供商在令牌的 aud 声明中填入的客户端 ID 相同。
• 公共 URL：客户端必须能够访问 MCP_SERVER_URL（例如 plexmcp.example.com），且应使用 HTTPS。
• 重定向 URI 不匹配（登录后出现提供商错误页面）：客户端的回调地址未列入提供商的重定向列表——请参阅步骤 1 中的表格。使用客户端请求的确切回调地址。对于 Codex，请将示例中的 <callback-id> 替换为实际的回调 ID；只有环回端口可以不同。
• 登录后客户端卡住／“Couldn't connect”：检查服务器日志中的 Token valid 与 Token validation failed。如果在 /token 成功后立即验证失败，通常意味着 MCP_OAUTH_AUDIENCE 与令牌的 aud 不匹配——取消设置以确认，然后将其设为客户端 ID。
• 首次请求缓慢：令牌验证会将发现元数据缓存至重启，并按 MCP_OAUTH_JWKS_CACHE_TTL 指定的秒数缓存 JWKS（默认值为 3600）。在提供商中轮换签名密钥后，请重启服务器或等待缓存过期。