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"

可用工具

本地开发和测试

直接运行MCP服务器

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

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

测试连接

python3  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

资源

• Plex官方网站
• Plex API文档
• PlexAPI Python库
• MCP协议
• MCP Python SDK
• 克劳德文件

贡献

欢迎投稿！请随意：

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

许可证

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

免责声明

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

______________________________________________________________________

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