Plex MCP 服务器

一个模型上下文协议 (MCP) 服务器，为 AI 助手提供对您的 Plex Media Server、Sonarr、Radarr 和 Trakt.tv 的全面访问权限——所有这些都集成在一个统一的服务器中。

这是什么？

此 MCP 服务器将您的 Plex Media Server 转换为一个可供 AI 查询的数据库。您可以向 AI 助手询问如下问题：

• “我最近看了哪些电影？”

• “向我展示过去一个月的观看统计数据”

• “我服务器上最受欢迎的内容是什么？”

• “在我的媒体库中查找动作片”

• “我的‘继续观看’列表中有什么？”

• “把那部新剧添加到 Sonarr”

• “我的下载队列里有什么？”

• “将我的观看历史同步到 Trakt”

• “给我推荐一些我没看过的电影”

Related MCP server: YARR Media Stack MCP Server

功能特性

开箱即用 45 个工具（启用写入操作后为 54 个）：

• Plex 媒体库管理 — 浏览媒体库、搜索媒体、获取详细元数据、列出播放列表和监视列表

• Tautulli 风格分析 — 观看统计、用户活动、热门内容、观看历史

• 个性化推荐 — 基于您的观看历史、流派、导演和演员的 AI 驱动电影建议。支持多用户 Plex 服务器的个人资料。

• Sonarr/Radarr 集成 — 浏览、搜索、添加剧集/电影、查看队列、触发下载

• Trakt.tv 同步 — OAuth 身份验证、观看历史同步、增强统计、Scrobbling。配置后，Trakt 数据通过捕获在 Plex 之外观看的电影来丰富推荐内容。

• 写入操作（可选） — 创建/编辑播放列表、更新元数据、管理监视列表

一个服务器，所有工具。 Trakt 和 Sonarr/Radarr 凭据是可选的——如果缺少密钥，需要它们的工具会返回有用的设置提示。您无需预先配置所有内容。

快速入门

先决条件

• Node.js 20+

• Plex Media Server（任何近期版本）

• Plex Token（如何获取您的令牌）

• 支持 MCP 的客户端（如 Claude Desktop 等）

安装

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

或者直接从 npm 安装：

npx plex-mcp-server

配置

1. 获取您的 Plex 令牌（参见下方的说明）

2. 配置您的 MCP 客户端（例如 Claude Desktop）：

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-mcp-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

仅需要 PLEX_TOKEN。 所有其他凭据均为可选——未配置服务的工具会返回清晰的错误消息说明如何设置，而不是导致服务器崩溃。

Sonarr/Radarr API 密钥可以在每个应用程序 Web UI 的 Settings > General > API Key 中找到。

Trakt.tv 设置需要一个 Trakt OAuth 应用程序。创建一个重定向 URI 为 urn:ietf:wg:oauth:2.0:oob 的应用，然后将客户端 ID 和密钥添加到您的配置中。服务器运行后，请让您的 AI 助手“使用 Trakt 进行身份验证”——它将引导您完成 OAuth 流程。详细说明请参阅 Trakt 设置指南。

在 v1.0.x 中，有三个独立的服务器二进制文件（build/index.js、build/plex-trakt-server.js、build/plex-arr-server.js）。在 v1.1.0+ 中，这些被一个统一的二进制文件取代：build/plex-mcp-server.js。

旧的二进制文件仍然有效，但会发出弃用警告。请更新您的 MCP 配置以指向 build/plex-mcp-server.js 并删除任何重复的服务器条目。

详细信息请参阅 迁移指南。

使用方法

配置完成后，您可以询问您的 AI 助手：

"What movies did I watch last week?"
"Show me my most popular TV shows this month"
"Give me viewing statistics for the past 30 days"
"Search for Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

推荐工作流

将 Plex 观看历史同步到 Trakt：

1. 设置 Trakt 凭据（见上文）

2. 询问：“使用 Trakt 进行身份验证” — 按照 OAuth 流程操作

3. 询问：“对我的 Plex 历史记录到 Trakt 进行一次试运行同步” — 预览将要同步的内容

4. 询问：“将我的 Plex 观看历史同步到 Trakt” — 执行实际同步

查找并添加新内容：

1. 询问：“在 Sonarr 中搜索 The Beverly Hillbillies” — 查找 TVDB ID

2. 询问：“将 The Beverly Hillbillies 添加到 Sonarr” — 它会自动检测质量配置文件和根文件夹

3. 询问：“我的 Sonarr 下载队列里有什么？” — 监控进度

获取个性化推荐：

1. 询问：“从我的媒体库中给我推荐一些电影”

2. 引擎会分析您的观看历史——流派、导演、演员、评分

3. 为每部未观看的电影评分，并返回匹配度最高的结果及原因

4. 对于多用户服务器，请指定用户：“为 Titus 推荐电影”

5. 如果配置了 Trakt，它也会自动使用您的 Trakt 历史记录——捕获您在 Plex 之外观看的电影（其他平台，或在启用跟踪之前观看的电影）

跨平台观看分析：

1. 询问：“向我展示我过去 30 天的 Plex 观看统计数据”

2. 询问：“我的 Trakt 统计数据是什么？” — 查看终身统计数据（观看的电影、小时数、里程碑）

3. 询问：“我这个月最受欢迎的电影是什么？”

可用功能

Plex 工具 (19 个工具)

写入操作 (9 个工具，可选)

设置 PLEX_ENABLE_MUTATIVE_OPS=true 以启用这些工具。它们允许您的 AI 助手对您的 Plex 服务器进行更改。请谨慎使用——虽然我们测试了这些工具，但不能保证绝对安全。在确认之前，请审查您的助手提出的更改。

Sonarr 工具 (8 个工具)

Radarr 工具 (8 个工具)

跨服务工具 (1 个工具)

Trakt 工具 (9 个工具)

获取您的 Plex 令牌

1. 在浏览器中打开 Plex Web App

2. 导航至 Settings > Account > Privacy

3. 点击底部的 "Show Advanced"

4. 复制您的 Plex Token

替代方法：

• 访问：http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account

• 查找 "Plex Token" 字段

项目结构

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (17 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

开发

脚本

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

从源码构建

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

贡献

欢迎贡献！请随时提交 Pull Request。对于重大更改，请先开启一个 issue 讨论您想要更改的内容。

开发指南

1. Fork 仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 提交更改 (git commit -m 'Add amazing feature')

4. 推送到分支 (git push origin feature/amazing-feature)

5. 开启 Pull Request

故障排除

常见问题

连接被拒绝：

• 验证您的 Plex 服务器正在运行

• 检查环境配置中的 PLEX_URL

• 确保端口（通常为 32400）正确

身份验证错误：

• 验证您的 Plex 令牌是否正确

• 在 Plex 设置中检查令牌权限

• 确保令牌未过期

空响应：

• 某些功能需要 Plex Pass

• 检查您的媒体库是否可访问

• 验证媒体是否已扫描且可用

Sonarr/Radarr 连接问题：

• 验证 Sonarr/Radarr 正在运行且可从 MCP 服务器主机访问

• 检查 API 密钥是否正确 (Settings > General > API Key)

• Sonarr 使用 /api/v3/ 的 API v3 — 确保您的 URL 不包含尾随路径

• 对于大型 Radarr 媒体库（2 万部电影以上），初始的 radarr_get_movies 调用可能需要长达 30 秒

Trakt 身份验证问题：

• 确保 TRAKT_CLIENT_ID 和 TRAKT_CLIENT_SECRET 均已设置

• 使用 trakt_authenticate 工具启动 OAuth 流程

• 使用来自 Trakt 的代码通过 trakt_complete_auth 完成身份验证

MCP 客户端问题：

• 确保路径设置为 build/plex-mcp-server.js（统一服务器）

• 检查 Node.js 是否在您的系统 PATH 中

• 验证客户端配置中是否设置了环境变量

获取帮助

• 开启一个 issue

• 查看现有的 讨论

• 查看 MCP 文档

要求

• Node.js 20.0.0 或更高版本

• Plex Media Server（任何近期版本）

• MCP 服务器与 Plex 服务器之间的网络访问

• 具有适当权限的有效 Plex 令牌

安全说明

• 妥善保管您的 Plex 令牌 - 切勿将其提交到版本控制中

• 使用环境变量进行敏感配置

• 在受信任的网络上运行 - 服务器直接与 Plex 通信

• 定期轮换令牌 - 考虑定期刷新令牌

• 写入操作默认禁用 - 仅在您信任 AI 助手的判断时启用

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢