Plex MCP Server (Niavasha)

Plex MCP服务器

A. 模型上下文协议（MCP） 该服务器为AI助手提供了对Plex媒体服务器、Sonarr、Radarr和Trakt.tv的全面访问，所有这些都可以从一个统一的服务器上访问。

 ](https://nodejs.org/)  

这是什么？

此MCP服务器将您的Plex媒体服务器转换为AI可查询的数据库。问你的AI助手一些问题，比如：

• *“我最近看了什么电影？”*
• *“显示我过去一个月的浏览统计数据”*
• *“我的服务器上最受欢迎的内容是什么？”*
• *“在我的库中查找动作电影”*
• *“我的继续观察名单上有什么？”*
• *“将新节目添加到Sonarr”*
• *“我的下载队列中有什么？”*
• *“将我的手表历史记录同步到Trakt”*
• *“给我推荐一些我没看过的电影”*

特性

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

• Plex库管理 --浏览库、搜索媒体、获取详细的元数据、列出播放列表和监视列表
• 陶图利风格分析 --查看统计数据、用户活动、热门内容、观看历史记录
• 个性化推荐 --基于你的观看历史、流派、导演和演员的人工智能电影建议。支持多用户Plex服务器的每个用户配置文件。
• 声纳/雷达集成 --浏览、搜索、添加系列/电影、查看队列、触发下载
• Trat.tv同步 --OAuth身份验证、观看历史同步、增强统计、涂鸦。配置后，Trakt数据通过捕捉在Plex之外观看的电影来丰富推荐。
• 写入操作 （选择加入）--创建/编辑播放列表、更新元数据、管理监视列表

一台服务器，所有工具。 Trakt和Sonarr/Radarr凭据是可选的——如果密钥丢失，需要它们的工具会返回一条有用的设置消息。您不需要预先配置所有内容。

快速开始

先决条件

• Node.js 20+
• Plex媒体服务器 （任何最新版本）
• Plex令牌 (如何获取您的代币)
• MCP兼容客户端 （克劳德桌面等）

安装

# 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令牌 （参见 说明如下)

1. 配置您的MCP客户端 （例如，克劳德桌面）：

{
  "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键 可以在 设置>常规>API密钥 在每个应用程序的web UI中。

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

Migrating from v1.0.x?

在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寻找贝弗利山人”* --查找TVDB ID
2. 问： *“将贝弗利山人加入索纳尔”* --它自动检测质量配置文件和根文件夹
3. 问： *“我的Sonarr下载队列中有什么？”* --监控进度

获取个性化推荐：

1. 问： *“从我的图书馆给我推荐一些电影”*
2. 该引擎分析你的手表历史——流派、导演、演员、收视率
3. 为每一部未观看的电影打分，并返回排名靠前的比赛及其原因
4. 对于多用户服务器，请指定用户： *“为提图斯推荐电影”*
5. 如果配置了Trakt，它也会自动使用您的Trakt历史记录——捕捉您在Plex之外观看的电影（在设置跟踪之前的其他平台）

跨平台查看分析：

1. 问： *“显示我过去30天的Plex浏览统计数据”*
2. 问： *“我的Trakt统计数据是什么？”* --查看生命周期统计数据（观看的电影、小时数、里程碑）
3. 问： *“这个月我最受欢迎的电影是什么？”*

可用功能

Plex工具（19个工具）

写入操作（9个工具，选择加入）

集 PLEX_ENABLE_MUTATIVE_OPS=true 以启用这些工具。它们允许您的AI助手对您的Plex服务器进行更改。 小心使用 --当我们测试这些工具时，无法保证。在确认之前，请先查看助理提出的更改。

Sonarr工具（8个工具）

雷达工具（8个工具）

交叉服务工具（1个工具）

Trakt工具（9个工具）

获取您的Plex令牌

1. 打开Plex Web应用程序 在浏览器中
2. 导航到“设置” >账户>隐私
3. 点击“显示高级” 在底部
4. 复制您的Plex令牌

替代方法：

• 访问： http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account
• 查找“Plex令牌”字段

项目结构

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

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

开发指南

1. 分叉存储库
2. 创建要素分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add amazing feature')
4. 推到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

故障排除

常见问题

连接被拒绝：

• 验证您的Plex服务器是否正在运行
• 检查 PLEX_URL 在您的环境配置中
• 确保端口（通常为32400）正确

身份验证错误：

• 验证您的Plex令牌是否正确
• 检查Plex设置中的令牌权限
• 确保令牌未过期

空响应：

• 某些功能需要Plex Pass
• 检查您的库是否可访问
• 验证介质是否已扫描并可用

Sonarr/Radarr连接问题：

• 验证Sonarr/Radarr是否正在运行，并且可以从MCP服务器主机访问
• 检查API密钥是否正确（“设置”>“常规”>“API密钥”）
• Sonarr使用API v3 /api/v3/ --确保您的URL不包含尾随路径
• 对于大型Radarr库（20k+电影），初始 radarr_get_movies 通话可能需要30秒

Trakt身份验证问题：

• 确保 TRAKT_CLIENT_ID 和 TRAKT_CLIENT_SECRET 都设置好了
• 使用 trakt_authenticate 启动OAuth流的工具
• 通过以下方式完成身份验证 trakt_complete_auth 使用Trakt中的代码

MCP客户端问题：

• 确保路径设置为 build/plex-mcp-server.js （统一服务器）
• 检查Node.js是否在您的系统PATH中
• 验证客户端配置中是否设置了环境变量

获取帮助

• 打开一个问题
• 检查现有 讨论
• 回顾 MCP文件

需求

• Node.js 20.0.0或更高
• Plex媒体服务器 （任何最新版本）
• 网络接入 MCP服务器和Plex服务器之间
• 有效的Plex令牌 具有适当的权限

安全说明

• 确保您的Plex令牌安全 -永远不要将其提交给版本控制
• 使用环境变量 用于敏感配置
• 在受信任的网络上运行 -服务器直接与Plex通信
• 定期代币轮换 -考虑定期刷新令牌
• 写入操作 默认情况下是禁用的——仅当您信任AI助手的判断时才启用

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• Anthropic 对于模型上下文协议
• 丛 令人惊叹的媒体服务器
• 陶图利 获取分析灵感
• 各种库和工具的开源社区

相关项目

• 模型上下文协议 -此服务器实现的标准
• 克劳德桌面 -热门MCP客户端
• 陶图利 -Plex监控和分析
• PlexAPI -Python Plex API库

______________________________________________________________________

基于对Plex和AI社区的热爱而构建