AI导哈

Plex媒体库向量化搜索工具

将Plex媒体库转换为可搜索的向量数据库，支持LLM代理查询，提供混合向量搜索和推荐功能。

  • by constructorfleet
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 constructorfleet/mcp-plex

使用说明

mcp综合体

mcp-plex 将您的Plex库转换为LLM代理可以查询的可搜索矢量数据库。 它将Plex元数据导入 Qdrant 并公开搜索和推荐 工具通过 模型上下文协议.

特性

  • 将Plex库加载到Qdrant矢量数据库中。
  • 媒体项目的混合密集和稀疏矢量搜索。
  • 标题搜索会自动删除前导文章（“The”、“A”、“An”等），现在又回到混合密集/稀疏向量相似性，因此仍然可以解决拼写错误（例如，要求“The Gentleman”返回“The Gentle”）。
  • 从参考项目中推荐类似的媒体。
  • 每当Plex删除或重新编号媒体时，自动修剪过时的Qdrant点，使收藏保持同步。
  • GPU支持数据加载和嵌入。

GPU依赖项会自动安装在Linux x86_64主机上。Arm64（包括Apple Silicon开发容器）退回到仅使用CPU的嵌入式堆栈，因此安装在任何地方都能成功。

安装

  1. 安装 uv.
  2. 将项目依赖关系（包括开发工具）与以下内容同步：
    uv sync --extra dev

用法

加载Plex元数据

将样本数据加载到Qdrant中：

uv run load-data --sample-dir sample-data

连续运行，运行之间有延迟：

uv run load-data --continuous --delay 600

Qdrant清理

现在，每次非样本加载器运行都会记录它处理的Plex评级密钥 清除该组中缺少评级键的Qdrant点。这保持 删除后的收藏与您当前的Plex库对齐，或 元数据更改。当出现以下情况时，会自动跳过清理 --sample-dir 是 供应时，捆绑的固定装置保持不变。

IMDb重试配置

加载器公开CLI标志（和镜像环境变量），用于控制 它如何重试IMDb查找，以及在点击时退出的力度有多大 HTTP 429 响应。在即席运行期间使用CLI选项或设置 通过Docker Compose或其他编排器部署时的环境变量。

CLI标志 环境变量 默认值 它如何影响重试
--imdb-cache IMDB_CACHE imdb_cache.json 将成功的IMDb响应存储在磁盘上，这样重复运行就可以跳过网络请求。缓存的命中永远不会进入重试管道。
--imdb-max-retries IMDB_MAX_RETRIES 3 IMDb返回速率限制响应时的重试次数。装载机制造 max_retries + 1 将ID推迟到重试队列之前的总尝试次数。
--imdb-backoff IMDB_BACKOFF 1.0 下次重试前的初始延迟（秒）。每次尝试失败后，加载器将延迟加倍（1秒→ 2s → 4s…），减缓重复的爆发。
--imdb-requests-per-window IMDB_REQUESTS_PER_WINDOW disabled 启用仅允许在下面定义的窗口内配置数量的IMDb请求的限制。不设置(None)无节流运行。
--imdb-window-seconds IMDB_WINDOW_SECONDS 1.0 油门使用的滑动窗口的持续时间。结合上述选项，当您需要保持在严格的配额下时，它可以平滑请求峰值。
--imdb-queue IMDB_QUEUE imdb_queue.json 重试队列在运行之间持久化的路径。在所有重试后继续失败的ID将附加在此处，并在下次执行时首先重新加载。

默认值在IMDb的限制下平衡了稳定的吞吐量。对于大多数人 家庭图书馆的标准设置无需修改即可工作。坚持 每当运行多个加载器容器或 希望队列驻留在共享存储上（例如，装载 /data/imdb 在 Docker），因此未完成的重试可以在容器重建或主机迁移中幸存下来。

积极的重试策略

uv run load-data \
  --imdb-max-retries 5 \
  --imdb-backoff 0.5 \
  --imdb-queue /data/imdb/aggressive_queue.json

设置 IMDB_MAX_RETRIES=5 和 IMDB_BACKOFF=0.5 将初始延迟减半 并且允许在回退到队列之前进行两次额外的重试尝试。随着 IMDB_REQUESTS_PER_WINDOW 如果未设置，装载机不会节流出站 请求，因此它将以更多为代价更快地从短暂的峰值中恢复 可能会触发硬IMDb速率限制。

保守重试策略

export IMDB_MAX_RETRIES=2
export IMDB_BACKOFF=2.0
export IMDB_REQUESTS_PER_WINDOW=10
export IMDB_WINDOW_SECONDS=60
export IMDB_QUEUE=/data/imdb/conservative_queue.json
uv run load-data

这些设置可减少重试次数，使初始延迟加倍，并应用 令牌桶限制，每分钟只允许10个请求。它们很有用 在多个工作者之间共享API密钥时。将队列延长到 共享路径确保挂起的ID继续逐步重试，即使 集装箱停止。

运行MCP服务器

通过stdio启动FastMCP服务器（默认）：

uv run mcp-server

通过端口8000上的SSE公开服务器：

uv run mcp-server --transport sse --bind 0.0.0.0 --port 8000

这种运输方式使用 /sse 默认情况下，除非您覆盖挂载。

当您的MCP客户端需要纯HTTP时，通过可流式HTTP公开服务器 流式响应体而不是SSE事件：

uv run mcp-server --transport streamable-http --bind 0.0.0.0 --port 8800

这种运输方式使用 /mcp 默认情况下，除非您覆盖挂载。

通过以下方式在同一主机和端口上的同一进程中运行SSE和流式HTTP 重复 --transport 并为每个运输工具提供自己的装载点：

uv run mcp-server \
  --transport sse \
  --transport streamable-http \
  --bind 0.0.0.0 \
  --port 8000 \
  --sse-mount /sse \
  --streamable-http-mount /mcp

集 MCP_TRANSPORT=sse,streamable-http 连同 MCP_BIND, MCP_PORT, MCP_SSE_MOUNT，以及 MCP_STREAMABLE_HTTP_MOUNT 配置相同 通过环境变量的行为。 MCP_MOUNT 仍然适用于单个HTTP 但共存需要不同的传输特定挂载点。 将SSE用于基于浏览器的连接器或任何本机支持的客户端 服务器已发送事件，并希望自动重新连接。选择可流式传输的HTTP 对于期望单个流式HTTP响应的客户端（例如CLI 终止SSE的工具或代理）。

提供 --recommend-user <username> （或设置 PLEX_RECOMMEND_USER)当 服务器应隐藏特定Plex帐户已监视的项目 建议。将旗帜与 --recommend-history-limit <count>/PLEX_RECOMMEND_HISTORY_LIMIT 约束 服务器检查了多少个如此大的监视历史条目（默认为500个） 库避免过多的Plex API调用。

运行时还读取 MCP_TRANSPORT, MCP_HOST （或 MCP_BIND), MCP_PORT, MCP_MOUNT, MCP_SSE_MOUNT，以及 MCP_STREAMABLE_HTTP_MOUNT 环境 变量。设置后，这些值会覆盖任何冲突的CLI标志，因此Docker 作曲家或其他编排者可以控制暴露的MCP端点，而无需 编辑容器命令。

服务器配置

其他环境变量调整服务器的搜索和服务方式 结果：

  • CACHE_SIZE 设置缓存在中的不同查询响应的最大数量 记忆。当部署同时处理许多用户或 重复复杂查询的长时间会话。
  • USE_RERANKER 切换交叉编码器重新排序。设置为 0 禁用 当你想要更低的延迟或没有GPU容量时，完全重新登录。
  • PLEX_PLAYER_ALIASES 提供备用玩家名称，以便命令保持不变 与自定义Plex客户端一致。以JSON或Python格式提供值 元组语法与服务器CLI解析器对齐。别名值可能会引用 Plex显示名称以及机器或客户端标识符和服务器 将在任何一个方向上解决合适的玩家。
  • PLEX_CLIENTS_FILE 指向YAML、JSON或XML-Plex客户端夹具 覆盖实时客户端发现。使用定义相同的路径 plex_clients_file=/abs/path/clients.yaml 在一个 .env 文件或设置 当您更喜欢配置文件而不是环境变量时，请使用配置文件。每 条目应包括Plex通常通过 /clients 端点，因此播放控制永远不会依赖于不稳定的发现 响应。
  • PLEX_RECOMMEND_USER 指定其观看历史记录应为的Plex用户 被排除在相似性建议之外。服务器缓存该用户的 对关键字进行评级，并将其从结果中过滤出来，以便呼叫者只看到看不见的内容 标题。
  • PLEX_RECOMMEND_HISTORY_LIMIT 限制服务器记录的观看历史记录数 在过滤推荐时为配置的用户获取。增加它 如果结果仍然包括之前观看的项目；减少它以减少 Plex API负载。

示例：

# Disable cross-encoder reranking to prioritize latency.
USE_RERANKER=0 uv run mcp-server

# Expand the in-memory cache to store up to 2,000 results.
CACHE_SIZE=2000 uv run mcp-server

# Map model-friendly player names to Plex devices by display name.
PLEX_PLAYER_ALIASES='{"living_room":"Plex for Roku"}' uv run mcp-server

# Alias keys can also point at Plex machine or client identifiers.
PLEX_PLAYER_ALIASES='{"movie_room":"6B4C9A5E-E333-4DB3-A8E7-49C8F5933EB1"}' \
  uv run mcp-server

# Tuple syntax is also accepted for aliases.
PLEX_PLAYER_ALIASES="[(\"living_room\", \"Plex for Roku\")]" uv run mcp-server

# Load a Plex clients fixture to bypass flaky discovery responses.
PLEX_CLIENTS_FILE=/opt/mcp/config/clients.yaml uv run mcp-server

#### Plex clients fixture

Defining a Plex clients fixture locks the server to a curated set of players so
playback continues even when the `/clients` endpoint returns stale metadata.
The file mirrors the format returned by Plex and may be authored in XML, JSON,
or YAML. Each `<Server>`/object entry maps directly to a `PlexClient` instance
with optional `<Alias>` elements that become friendly names during player
matching. For example:

```xml
<MediaContainer size="2">
  <Server name="Apple TV" address="10.0.12.122" port="32500"
          machineIdentifier="243795C0-C395-4C64-AFD9-E12390C86595"
          product="Plex for Apple TV" protocolCapabilities="playback,playqueues,timeline">
    <Alias>Movie Room TV</Alias>
    <Alias>Movie Room</Alias>
  </Server>
  <Server name="Apple TV" address="10.0.12.94" port="32500"
          machineIdentifier="243795C0-C395-4C64-AFD9-E12390C86212"
          product="Plex for Apple TV" protocolCapabilities="playback,playqueues,timeline">
    <Alias>Office AppleTV</Alias>
    <Alias>Office TV</Alias>
    <Alias>Office</Alias>
  </Server>
</MediaContainer>

相同的结构在JSON或YAML中使用 MediaContainer 和 Server 钥匙。加载文件时，服务器实例化 PlexClient 对象与 提供的元数据，并在匹配播放命令时重用别名列表。


### Embedding Models

Both the loader and server default to `BAAI/bge-small-en-v1.5` for dense
embeddings and `Qdrant/bm42-all-minilm-l6-v2-attentions` for sparse embeddings.
Override these by setting `DENSE_MODEL`/`SPARSE_MODEL` environment variables or
using `--dense-model`/`--sparse-model` CLI options:

```bash
uv run load-data --dense-model my-dense --sparse-model my-sparse
uv run mcp-server --dense-model my-dense --sparse-model my-sparse

交叉编码器重新排序默认为 cross-encoder/ms-marco-MiniLM-L-6-v2. 集 RERANKER_MODEL 或通过 --reranker-model 指向另一个模型：

uv run mcp-server --reranker-model sentence-transformers/ms-marco-mini

码头工人

Dockerfile基于以下内容构建支持GPU的映像 nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 使用 uv 依赖性 管理。构建并运行加载器：

docker build -t mcp-plex .
docker run --rm --gpus all mcp-plex --sample-dir /data

使用 --continuous 和 --delay 旗帜与 docker run 保持装载机 在循环中运行。

依赖层工作流

Docker构建现在使用安装依赖项 docker/pyproject.deps.toml一 清单反映了应用程序的运行时要求。保持 [project] 元数据——包括 version--与根相同 pyproject.toml 所以 uv sync 可以重用共享 uv.lock 没有 验证错误。这 Dockerfile 副本清单和 uv.lock 第一， 跑 uv sync --no-dev --frozen --manifest-path pyproject.deps.toml，并且仅 然后复制源树的其余部分。这保留了重依赖层 即使应用程序版本更改，也会缓存。

切割脱模剂时：

  1. 根据需要更新依赖关系并刷新 uv.lock 随着 uv lock.
  2. 构建映像两次以确认依赖层缓存命中：
    docker build -t mcp-plex:release-test-1 .
docker build -t mcp-plex:release-test-2 .
    第二个构建应该重用 uv sync 层只要 docker/pyproject.deps.toml 和 uv.lock 没有变化。
  3. 一旦对缓存行为满意，标记并推送最终版本映像。

Docker Compose

包括 docker-compose.yml 启动Qdrant和MCP服务器。

  1. 集 PLEX_URL, PLEX_TOKEN，以及 TMDB_API_KEY 在您的环境中（或 .env 文件）。
  2. 启动服务：
    docker compose up --build
  3. （可选）将样本数据加载到Qdrant中：
    docker compose run --rm loader load-data --sample-dir sample-data

服务器将连接到 qdrant 服务在 http://qdrant:6333 和 在以下位置公开SSE端点 http://localhost:8000/mcp.

Qdrant配置

连接设置可以通过环境变量提供：

  • QDRANT_URL –完整的URL或SQLite路径。
  • QDRANT_HOST/QDRANT_PORT –HTTP主机和端口。
  • QDRANT_GRPC_PORT –gRPC端口。
  • QDRANT_HTTPS –设置为 1 启用HTTPS。
  • QDRANT_PREFER_GRPC –设置为 1 更喜欢gRPC。

发展

运行linting和测试 uv:

uv run ruff check .
uv run pytest

VS代码开发容器

这 .devcontainer 安装程序构建在 mcr.microsoft.com/devcontainers/base:ubuntu-22.04, 复制 uv 二进制文件来自 ghcr.io/astral-sh/uv，并运行 uv sync --extra dev 之后 容器已创建，因此本地 .venv 火柴 uv.lock.在VS Code中打开文件夹并选择 开发容器：在容器中重新打开 使用它。定义挂载一个持久 uv-cache 体积在 /home/vscode/.cache/uv 因此Python下载和轮子可以在重建后幸存下来；移除 如果你需要一个全新的安装。覆盖 UV_DISTRO_IMAGE 在内部构建论点 .devcontainer/devcontainer.json 以固定特定的紫外线释放（例如， ghcr.io/astral-sh/uv:0.9.25)然后跑 开发容器：重建容器 应用更改。

贡献

请阅读 代理商.md 用于提交消息约定和PR 要求。

许可证

根据MIT许可证分发。看 许可证 了解更多信息。

相关 MCP