AI导哈

Plex AI管理助手

Plex Assistant MCP是一款通过AI助手（如Claude）管理Plex媒体库的服务，支持自然语言搜索、播放列表管理、观看状态标记和库统计等功能。

  • by axelterrier
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 axelterrier/plex-assistant-mcp

使用说明

Plex助理MCP

🎬 MCP（模型上下文协议）服务器，用于通过Claude等人工智能助手管理您的Plex库。

Plex Assistant MCP使您能够直接从Claude Desktop或任何兼容MCP的客户端控制Plex。使用自然语言搜索内容、管理播放列表、将项目标记为已观看，以及获取库统计信息！

特性

  • 🔍 搜索 -在所有库中查找电影、节目、音乐和照片
  • 📊 统计 -查看库概述和内容细分
  • 👥 现场会议 -看看谁在看什么
  • 📋 播放列表 -创建、查看和管理播放列表
  • ✅ 观察名单 -将内容标记为已观看/未观看
  • 🏷️ 集合 -将内容组织到自定义集合中
  • 📡 察看连接信息 -获取Plex服务器详细信息和状态
  • 🎯 高级搜索 -按库、媒体类型等筛选

先决条件

  • python ≥ 3.12
  • 紫外线 -快速Python包管理器(在此处安装)
  • Plex服务器 -正在运行具有管理员权限的实例
  • Claude桌面版 -最新版本（或任何兼容MCP的客户端）

快速开始

1.克隆或创建项目

# Create project directory
mkdir plex-assistant-mcp
cd plex-assistant-mcp

# Or clone if you have a repo
git clone https://github.com/yourusername/plex-assistant-mcp.git
cd plex-assistant-mcp

2.用uv初始化

# Initialize Python project
uv init

# Install dependencies
uv sync

3.配置Plex连接

创建一个 .env 项目根目录下的文件：

PLEX_URL=http://your-ip:32400
PLEX_TOKEN=your-plex-auth-token

如何找到您的Plex令牌

方法1：使用PlexAPI（自动）

python3 -c "from plexapi.myplex import MyPlexAccount; account = MyPlexAccount(username='your-email', password='your-password'); print(account.authenticationToken)"

方法2：浏览器开发工具

  1. 打开https://app.plex.tv/desktop/
  2. 打开DevTools（F12）→ 网络选项卡
  3. 查找任何请求 plex.tv
  4. 查找标题 X-Plex-Token -复制该值

方法3:Plex设置

  1. 打开Plex Web应用程序
  2. 设置→ 您的账户→ 滚动到“授权应用程序”
  3. 在Plex帐户设置中生成令牌

4.配置克劳德桌面

编辑您的Claude Desktop配置文件：

窗户：

%APPDATA%\Claude\claude_desktop_config.json

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Linux：

~/.config/Claude/claude_desktop_config.json

添加以下MCP服务器配置：

{
  "mcpServers": {
    "plex-assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YourUsername/Documents/plex-assistant-mcp",
        "run",
        "src/plex_assistant_mcp/main.py"
      ],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your-actual-token-here"
      }
    }
  }
}

重要提示：

  • 更新 --directory 与您的安装相匹配的路径
  • 替换 PLEX_URL 使用您的实际Plex服务器地址
  • 替换 PLEX_TOKEN 使用您的实际身份验证令牌

5.重新启动克劳德桌面

关闭并重新打开Claude Desktop。Plex工具现在可以使用了！

使用示例

搜索内容

"Search for The Matrix in my library"
"Find all movies from 2024"
"Show me TV shows with drama in the title"

图书馆管理

"How many items do I have in my Plex library?"
"Show me my movie library statistics"
"What libraries do I have?"

活动会话

"Who's watching something right now?"
"Show me current Plex sessions"

观察名单和标记

"Mark The Dark Knight as watched"
"Add Oppenheimer to my watchlist"
"Mark this show as unwatched"

播放列表

"Create a playlist called Favorites"
"Show me all my playlists"
"Get my available playlists"

集合

"Add this to my Sci-Fi collection"
"Mark Inception as part of my Best Movies collection"

可用工具

工具 说明
test_plex_connection 测试与Plex服务器的连接
get_server_info 获取Plex服务器详细信息
get_libraries 列出所有媒体库
get_library_statistics 获取图书馆统计数据和明细
search_content 在所有库中搜索
search_in_library 在特定库中搜索
get_currently_playing 查看活动会话和正在观看的内容
get_playlists 列出所有播放列表
create_playlist 创建新的播放列表
add_to_watchlist 将项目添加到观察列表
toggle_watched 将内容标记为已观看/未观看
mark_collection 将项目添加到集合

本地开发和测试

直接运行MCP服务器

export PLEX_URL="http://your-ip:32400"
export PLEX_TOKEN="your-token"
uv run src/plex_assistant_mcp/main.py

服务器将启动并通过stdio等待MCP命令。

测试连接

python3 << 'EOF'
from src.plex_assistant_mcp.plex_client import PlexClient
import os

client = PlexClient(
    os.getenv("PLEX_URL", "http://localhost:32400"),
    os.getenv("PLEX_TOKEN", "")
)
print("Connection test:", client.test_connection())
print("Server info:", client.get_server_info())
EOF

项目结构

plex-assistant-mcp/
├── src/
│   └── plex_assistant_mcp/
│       ├── __init__.py           # Package initialization
│       ├── main.py               # MCP server entry point
│       ├── plex_client.py         # Plex API wrapper
│       └── tools.py              # MCP tool definitions & handlers
├── pyproject.toml                # Project configuration
├── requirements.txt              # Python dependencies
├── .env.example                  # Example environment variables
└── README.md                     # This file

故障排除

错误： PLEX_TOKEN environment variable not set

解决方案： 确保你的 .env 文件存在并包含：

PLEX_URL=http://your-ip:32400
PLEX_TOKEN=your-token

错误： Connection refused 或 Unable to connect

解决：

  • 验证Plex是否在您的服务器上运行
  • 检查一下 PLEX_URL 正确（包括IP和端口）
  • 在浏览器中测试URL： http://your-ip:32400
  • 检查服务器上的防火墙规则
  • 确保Claude Desktop可以访问您的Plex服务器

错误： HTTP 401: Unauthorized

解决：

  • 验证您的 PLEX_TOKEN 是正确的
  • 如果旧令牌过期，则生成新令牌
  • 确保使用正确的身份验证令牌格式

错误： No results found 搜索

解决：

  • 尝试不同的拼写或关键字
  • 如果可能的话，使用准确的标题
  • 检查Plex库中是否存在内容
  • 验证库是否已正确索引

Claude Desktop未显示Plex工具

解决：

  • 验证配置文件的JSON格式是否正确
  • 完全重新启动Claude Desktop（不仅仅是刷新）
  • 检查Claude Desktop设置中的MCP服务器日志
  • 验证 --directory 路径正确
  • 手动测试连接以确保Plex可访问

API 参考

PlexClient方法

# Connection
test_connection() -> bool

# Server & Libraries
get_server_info() -> Dict[str, Any]
get_libraries() -> List[Dict[str, Any]]
get_library_statistics() -> Dict[str, Any]

# Search & Discovery
search(query: str, limit: int = 20) -> List[Dict[str, Any]]
search_in_library(query: str, library_key: str, media_type: str = "") -> List[Dict[str, Any]]
find_item(title: str) -> Optional[Dict[str, Any]]

# Sessions
get_currently_playing() -> List[Dict[str, Any]]

# Playlists
get_playlists() -> List[Dict[str, Any]]
create_playlist(title: str, items: Optional[List] = None, description: str = "") -> Dict[str, Any]

# Content Management
set_watched(item_key: str) -> bool
set_unwatched(item_key: str) -> bool
add_to_collection(item_key: str, collection_name: str) -> bool
remove_from_collection(item_key: str, collection_name: str) -> bool

资源

贡献

欢迎投稿！请随意：

  • 报告错误和问题
  • 建议新功能
  • 提交拉取请求
  • 改进文档

许可证

这个项目是开源的，可以在MIT许可证下使用。

免责声明

该项目与Plex或Anthropic没有正式关联。使用风险由您自行承担，并确保您有适当的授权访问您的Plex服务器。

由以下材料制成❤️ 适用于希望使用人工智能进行库管理的Plex爱好者

相关 MCP