Plex MCP Server

Plex MCP 服务

使用 Claude 搜索和管理 Plex 媒体库。本项目由 Claude 和一位热衷于音频内容的技术爱好者共同积极开发。他主要使用 Plex 享受音频内容，也想看看在不太了解自己在做什么的情况下能完成多少事情。结果可能各不相同，不过大概会有不错的结果。

快速开始

通过 Smithery 安装（推荐）

npx -y @smithery/cli install @vyb1ng/plex-mcp --client claude

Claude Desktop 手动设置

将以下内容添加到 Claude Desktop 的 MCP 设置中：

{
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": ["plex-mcp"],
      "env": {
        "PLEX_URL": "http://your-plex-server:32400"
      }
    }
  }
}

身份验证

选项 1：OAuth（推荐）

• 使用 authenticate_plex 工具获取登录 URL
• 通过浏览器登录

选项 2：静态令牌

• 在 env 部分添加 "PLEX_TOKEN": "your_token"
• 从 Plex Support 获取令牌

注意： 将 your-plex-server:32400 替换为实际的 Plex 服务地址和端口。

HTTP 调试日志

排查连接问题时，可以启用全面的 HTTP 请求／响应日志记录：

{
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": ["plex-mcp"],
      "env": {
        "PLEX_URL": "http://your-plex-server:32400",
        "MCP_HTTP_DEBUG": "true"
      }
    }
  }
}

当 MCP_HTTP_DEBUG=true 时，服务会记录：

• 请求详情：方法、URL、标头、参数、耗时
• 响应详情：状态码、标头、响应大小、持续时间
• 错误诊断：连接详情、TLS/SSL 证书信息、故障排查建议
• 性能指标：DNS 查询、TCP 连接、TLS 握手耗时
• 安全性：所有敏感标头（令牌、身份验证信息）都会自动脱敏

所有日志均为结构化 JSON，并包含用于跟踪请求／响应的关联 ID。

可以做什么

搜索和浏览

• 搜索电影、电视节目、音乐和其他内容
• 浏览媒体库和合集
• 查看最近添加的内容和观看记录

音乐探索

• 使用自然语言探索音乐（“90 年代的歌曲”、“我没听过的摇滚乐队”）
• 根据聆听习惯提供智能推荐
• 智能随机推荐，带来多样性和惊喜
• 发现相似艺术家并探索音乐流派

播放列表

• 创建和管理播放列表
• 将项目添加到现有播放列表
• 浏览播放列表内容

媒体信息

• 获取详细的媒体信息（编解码器、比特率、文件大小）
• 查看观看状态和进度
• 查看媒体库统计数据和聆听统计数据

资源（数据访问）

• 通过 URI 访问结构化数据：plex://libraries、plex://recent、plex://playlists
• 媒体库专属数据：plex://library/{id}、plex://library/{id}/recent
• 服务统计数据和连接状态
• 用于分析和自动化的 JSON 格式数据

提示词（AI 辅助）

• playlist_description：生成有创意的播放列表描述
• content_recommendation：获取个性化内容推荐
• smart_playlist_rules：创建智能播放列表条件和规则
• media_analysis：分析媒体库内容和模式
• server_troubleshooting：诊断服务连接问题

状态

✅ 正常运行： 搜索、浏览、播放列表、媒体信息、媒体库统计数据、观看记录、合集、音乐探索、资源、提示词

❌ 已停用： 智能播放列表（筛选逻辑失效）

🚧 计划中： 浏览远程服务

开发

想要贡献代码？让 Claude 使用你的本地版本：

{
  "mcpServers": {
    "plex-dev": {
      "command": "node",
      "args": ["/path/to/plex-mcp/index.js"],
      "env": {
        "PLEX_URL": "http://your-plex-server:32400"
      }
    }
  }
}

对我们来说一切正常。如果你那里无法运行，那我们也尽力了。来找我们聊聊吧，我们不会咬人。大概不会。