Plex

这是一组 MCP，可将任何 LLM 变成电影／电视节目下载媒体管理器。它可以访问你的 Plex 媒体库和 qbittorrent 客户端，因此了解你已有的内容和想要的内容。

设置

使用 skills 设置是最简单的方法：

npx skills add konsumer/aitorrent

确保环境中包含 .env.example 中的环境变量，就可以开始使用了。

配置凭据：

cp .env.example .env
# Edit .env with your Plex URL and token

Plex Token：在 https://app.plex.tv 登录，点击任意媒体项目，点击三个点，选择“Get Info”，点击“View XML”（左下角），然后从地址栏中的 URL 复制 X-Plex-Token 值。

TMDB API Key（可选）：用于查找缺失的剧集，以及搜索媒体库中没有的节目：

1. 在 https://www.themoviedb.org 创建免费账户
2. 前往 Settings > API（https://www.themoviedb.org/settings/api）
3. 点击“Request an API Key”（如果尚未申请）
4. 选择“Developer”并填写表单（应用类型可以选择“Personal project”）
5. 获批后，复制 API Key (v3 auth) 的值（不要复制“API Read Access Token”）
6. 将其添加到 .env，格式为 TMDB_API_KEY=your_key_here

重要：请使用“API Key (v3 auth)”字段，它是一个 32 位十六进制字符串。“API Read Access Token”（以“eyJ”开头的 JWT 格式）无法用于此工具。

qBittorrent：确保 qBittorrent 正在运行并已启用 Web UI。默认凭据为 admin/adminadmin，可在 Tools > Options > Web UI 中配置。

工具

CLI 用法

无需安装即可通过 uvx 直接运行 CLI 工具：

# List your collection names
uvx --from aitorrent aitorrent-plex-cli list

# List all your shows (show/season/episode) in "TV Shows" collection
uvx --from aitorrent aitorrent-plex-cli list "TV Shows"

# List all your movies by collection in "Movies" collection
uvx --from aitorrent aitorrent-plex-cli list "Movies"

# List all your music by artist/album in "Music" collection
uvx --from aitorrent aitorrent-plex-cli list "Music"

# Show what you're currently watching (on-deck and in-progress shows with relative times)
uvx --from aitorrent aitorrent-plex-cli watching

watching 命令会显示：

• On Deck：你正在观看的剧集／电影及其进度百分比
• In Progress：你尚未看完的电视剧、完成情况统计，以及上次观看时间（例如，“2 天前”）

TMDB CLI

tmdbinfo.py 脚本可搜索 The Movie Database（需要 TMDB API key）：

# Search for TV shows
uvx --from aitorrent aitorrent-tmdb-cli search-shows "Star Trek Lower Decks"

# Get detailed show information (seasons, episodes, air dates)
uvx --from aitorrent aitorrent-tmdb-cli show-details 85948

# Get specific season details
uvx --from aitorrent aitorrent-tmdb-cli season-details 85948 1

# Search for movies
uvx --from aitorrent aitorrent-tmdb-cli search-movies "The Matrix"

# Get detailed movie information
uvx --from aitorrent aitorrent-tmdb-cli movie-details 603

此工具适用于查找 Plex 媒体库中没有的节目／电影，以及获取剧集播出日期。

qBittorrent CLI

qbtinfo.py 脚本用于管理种子下载和自动化操作：

# List all torrents
uvx --from aitorrent aitorrent-qbt-cli list

# List only downloading torrents
uvx --from aitorrent aitorrent-qbt-cli list downloading

# Add a torrent by magnet link or URL
uvx --from aitorrent aitorrent-qbt-cli add "magnet:?xt=urn:btih:..." --path "/path/to/save" --category "TV Shows"

# List RSS feeds
uvx --from aitorrent aitorrent-qbt-cli rss list-feeds

# Add an RSS feed
uvx --from aitorrent aitorrent-qbt-cli rss add-feed "https://showrss.info/user/123456.rss?magnets=true&namespaces=true&name=null&quality=1080p" --folder "TV Shows"

# Refresh RSS feeds
uvx --from aitorrent aitorrent-qbt-cli rss refresh

# List RSS auto-download rules
uvx --from aitorrent aitorrent-qbt-cli rss list-rules

# Create RSS rule for a show (auto-downloads new episodes)
uvx --from aitorrent aitorrent-qbt-cli rss add-show "Star Trek: Strange New Worlds" --season 2 --quality 1080p --category "TV Shows" --feeds "TV Shows\ShowRSS"

# Attach an existing rule to specific feeds
uvx --from aitorrent aitorrent-qbt-cli rss attach-rule "Star Trek: Strange New Worlds S02" "TV Shows\ShowRSS,TV Shows\EZTV"

RSS 自动下载功能会在 RSS 订阅源中出现新剧集时自动下载，非常适合追更正在播出的节目。重要：规则必须关联到特定订阅源才能触发；创建规则时使用 --feeds 参数，或使用 attach-rule 关联现有规则。

MCP 服务用法

同样的功能也可作为 MCP（Model Context Protocol）服务供 LLM 使用：

将以下内容添加到 LLM 的 MCP 设置中（~/.claude.json）：

{
  "mcpServers": {
    "plex-info": {
      "command": "uvx",
      "args": ["--from", "aitorrent", "aitorrent-plex", "mcp"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",
        "TMDB_API_KEY": "your_tmdb_api_key_here"
      }
    },
    "tmdb-info": {
      "command": "uvx",
      "args": ["--from", "aitorrent", "aitorrent-tmdb", "mcp"],
      "env": {
        "TMDB_API_KEY": "your_tmdb_api_key_here"
      }
    },
    "qbt-info": {
      "command": "uvx",
      "args": ["--from", "aitorrent", "aitorrent-qbt", "mcp"],
      "env": {
        "QBT_URL": "http://localhost:8080",
        "QBT_USERNAME": "admin",
        "QBT_PASSWORD": "adminadmin"
      }
    }
  }
}

使用 Claude Code 也可以这样操作：

claude mcp add plex-info --transport stdio \
  --env PLEX_URL=http://localhost:32400 \
  --env PLEX_TOKEN=your_plex_token_here \
  --env TMDB_API_KEY=your_tmdb_api_key_here \
  -- uvx --from aitorrent aitorrent-plex mcp

claude mcp add tmdb-info --transport stdio \
  --env TMDB_API_KEY=your_tmdb_api_key_here \
  -- uvx --from aitorrent aitorrent-tmdb mcp

claude mcp add qbt-info --transport stdio \
  --env QBT_URL=http://localhost:8080 \
  --env QBT_USERNAME=admin \
  --env QBT_PASSWORD=adminadmin \
  -- uvx --from aitorrent aitorrent-qbt mcp

LLM 将可以使用以下工具：

媒体库与内容：

• plex_list_libraries - 列出所有 Plex 媒体库及其类型
• plex_list_library_content - 列出指定媒体库中的所有内容（含季／集的电视剧、按合集分组的电影，或按艺人／专辑分组的音乐）
• plex_search - 按标题搜索所有媒体库或指定媒体库中的媒体

详细信息：

• plex_get_show_details - 获取指定电视剧的详细信息，包括所有季、剧集和播出日期（适用于查找缺失的剧集）
• plex_get_movie_details - 获取指定电影的详细信息，包括演员、类型、合集和评分
• plex_get_artist_details - 获取指定音乐艺人的详细信息，包括所有专辑和曲目

观看状态与进度：

• plex_get_on_deck - 获取当前“待看”（继续观看）项目，显示用户正在观看的内容
• plex_get_in_progress_shows - 获取观看进度不完整的电视剧，并显示完成百分比，非常适合查找用户正在追看的剧集
• plex_get_show_watch_status - 获取指定电视剧的详细观看状态（每季中已观看和未观看的剧集）
• plex_get_recently_added - 获取最近添加的项目

高级下载辅助工具：

• plex_get_episodes_to_download - 高级工具：获取所有需要下载的剧集，并提供预先格式化的搜索查询和下载路径（最大限度减少上下文用量）
• plex_find_missing_episodes - 将 TMDB 剧集列表与 Plex 媒体库进行比对，以查找缺失的剧集（需要 TMDB_API_KEY）
• plex_get_next_episodes - 获取上一集观看完毕后接下来尚未观看的剧集（需要 TMDB_API_KEY）
• plex_format_torrent_query - 将电视剧信息格式化为种子搜索查询（例如，“Star Trek Strange New Worlds 2022 S02E05 1080p”）

TMDB 工具（独立的 tmdb-info MCP）：

• tmdb_search_shows - 按名称在 The Movie Database 中搜索电视剧
• tmdb_get_show_details - 获取电视剧详细信息，包括所有季和剧集
• tmdb_get_season_details - 获取指定季的详细信息
• tmdb_search_movies - 按片名在 TMDB 中搜索电影
• tmdb_get_movie_details - 获取电影的详细信息

文件系统与下载路径管理：

• plex_get_show_path - 获取存储电视剧剧集的实际文件系统路径（例如，/media/video/tv/Doctor Who）
• plex_suggest_download_path - 智能建议剧集的下载位置（使用现有电视剧路径，或新剧集的媒体库位置）
• plex_list_library_subdirs - 列出媒体库中的所有电视剧文件夹（适用于模糊匹配或检查已有内容）

qBittorrent 种子管理：

• qbt_get_torrents - 获取种子列表，可选按状态筛选（下载中、已完成等）
• qbt_get_torrent_details - 获取指定种子的详细信息
• qbt_add_torrent - 通过磁力链接或 URL 添加种子，可选设置保存路径和分类
• qbt_get_categories - 获取所有种子分类及其保存路径
• qbt_create_category - 创建新分类（适用于按电视剧或合集整理）
• qbt_get_transfer_info - 获取当前下载/上传速度和统计信息

qBittorrent 搜索：

• qbt_search_torrents - 使用 qBittorrent 已安装的插件搜索种子（返回按做种人数排序的磁力链接）
• qbt_get_search_plugins - 获取已安装的搜索插件列表
• qbt_get_downloading_episodes - 高级工具：解析当前正在下载的种子，提取剧集信息（防止重复下载）

qBittorrent RSS 订阅源管理：

• qbt_get_rss_feeds - 获取所有 RSS 订阅源和文件夹（用于查看已配置的订阅源）
• qbt_add_rss_feed - 添加新的 RSS 订阅源 URL
• qbt_remove_rss_feed - 移除 RSS 订阅源或文件夹
• qbt_refresh_rss_feed - 手动刷新 RSS 订阅源，以检查是否有新项目

qBittorrent RSS 自动化：

• qbt_get_rss_rules - 获取所有 RSS 自动下载规则（显示规则关联的订阅源）
• qbt_create_show_rss_rule - 创建 RSS 规则，自动下载电视剧的新剧集（可指定要关联的订阅源）
• qbt_attach_rule_to_feeds - 将现有规则关联到指定订阅源（重要：除非关联，否则规则不会触发！）
• qbt_delete_rss_rule - 删除 RSS 自动下载规则

MCP 使用场景示例

借助这些工具，大模型可以帮你处理如下请求：

基础媒体库管理：

• “我喜欢《绝命毒师》” → 搜索该剧，获取详情，查看你有哪些剧集
• “我目前在看哪些剧？” → 获取待看和正在观看的剧集，查看你正在追哪些剧
• “查找漫威合辑中的电影” → 搜索媒体库并按合辑筛选
• “显示所有昆汀·塔伦蒂诺的电影” → 搜索并获取该合辑中电影的详情
• “我有哪些披头士乐队的专辑？” → 搜索艺人并获取完整的唱片目录
• “我的媒体库里有什么新内容？” → 获取最近添加的内容

种子下载规划（使用 TMDB）：

• “下载我正在看的剧集的下一季” → 获取正在观看的剧集 → 查找缺失的剧集 → 格式化种子查询
• “《办公室》我还缺哪些剧集？” → 将 TMDB 数据与 Plex 对比 → 生成缺失剧集列表
• “我想补齐《神秘博士》合集，但不要太老的剧集” → 查找缺失的剧集 → 按年份筛选 → 格式化种子查询
• “下载《星际迷航：奇异新世界》的新剧集” → 获取下一集 → 检查是否已播出 → 使用“1080p”格式化种子查询
• “以 1080p 下载《绝命毒师》第 2 季第 5 至 10 集” → 按首选画质格式化多个种子查询

完整工作流（Plex + qBittorrent + TMDB）：

• “我正在看《星际迷航：奇异新世界》，有新剧集时自动下载” →

  1. plex_get_in_progress_shows() - 确认你正在看 SNW
  2. plex_get_next_episodes("Star Trek: Strange New Worlds") - 查找已播出但缺失的第 2 季第 6 集
  3. plex_get_show_path("Star Trek: Strange New Worlds") - 获取现有路径：/media/video/tv/Star Trek Strange New Worlds
  4. plex_format_torrent_query("Star Trek Strange New Worlds", 2, 6, 2022, "1080p") - 创建搜索查询
  5. [用户将搜索种子并获取 magnet 链接]
  6. qbt_add_torrent(magnet_link, save_path="/media/video/tv/Star Trek Strange New Worlds") - 将内容下载到正确的文件夹
  7. qbt_get_rss_feeds() - 检查已配置的 RSS 订阅源（例如，“TV Shows\ShowRSS”）
  8. qbt_create_show_rss_rule("Star Trek Strange New Worlds", season=2, quality="1080p", save_path="/media/video/tv/Star Trek Strange New Worlds", feed_paths=["TV Shows\\ShowRSS"]) - 从指定订阅源自动下载后续剧集到同一位置

• “补齐我的《神秘博士》合集，但跳过较老的剧集” →

  1. plex_find_missing_episodes("Doctor Who") - 获取所有缺失的剧集
  2. plex_get_show_path("Doctor Who") - 获取现有路径：/media/video/tv/Doctor Who
  3. 筛选 air_date >= 2005 的剧集（现代版《神秘博士》）
  4. 对每集缺失的剧集：格式化种子查询 → 搜索 → 使用正确的 save_path 添加到 qBittorrent
  5. 下载的内容会自动存入 Plex 中现有的《神秘博士》文件夹

• “下载尚未添加到我的媒体库的新剧” →

  1. plex_search("The Expanse") - 在 Plex 中找不到该剧
  2. plex_list_library_subdirs("TV Shows") - 检查现有剧集文件夹以避免重复
  3. plex_suggest_download_path("The Expanse", "TV Shows") - 建议路径：/media/video/tv/The Expanse
  4. 将剧集下载到建议路径
  5. Plex 会在下次扫描媒体库时自动识别这些内容