项目简介

mcp-plex 是一个基于 Model Context Protocol (MCP) 构建的服务器应用，旨在将您的 Plex 媒体库转换为一个可供大型语言模型 (LLM) 代理查询和交互的智能数据库。它通过将 Plex 媒体元数据摄取到 Qdrant 向量数据库中，为 LLM 提供强大的搜索、推荐和媒体控制功能。

主要功能点

媒体库智能化： 将您的Plex电影、电视节目等元数据加载到Qdrant向量数据库中，支持高级搜索和复杂查询。
混合向量搜索： 提供密集向量和稀疏向量的混合搜索能力，让LLM能通过自然语言精确查找媒体内容。
智能推荐： 根据指定参考媒体项，推荐相似内容，并可排除用户已观看的项目，帮助用户发现新内容。
媒体播放控制： 允许LLM通过工具调用来远程控制Plex播放器，包括播放、暂停、快进、倒带、跳过、切换字幕和音轨等。
GPU加速： 支持GPU加速的数据加载和嵌入生成，提升处理效率。
上下文提供： 以标准化的方式向LLM客户端提供Plex媒体资源、可调用工具和可定制的Prompt模板。

安装步骤

安装 'uv'：
- 'mcp-plex' 使用 'uv' 工具进行依赖管理。请首先安装 'uv'。您可以访问 'uv' 的官方GitHub仓库（'https://github.com/astral-sh/uv'）获取详细安装指南。

同步项目依赖：

安装 'uv' 后，进入 'mcp-plex' 项目的根目录，运行以下命令同步所有项目依赖（包括开发工具）：
```
uv sync --extra dev
```

重要提示： 在运行服务器之前，您需要提供访问Plex服务器和TMDb API的凭据。这些通常通过环境变量设置，例如：

export PLEX_URL="http://your-plex-server-ip:32400"
export PLEX_TOKEN="your-plex-api-token"
export TMDB_API_KEY="your-tmdb-api-key"

或者将它们写入项目根目录下的 '.env' 文件中。

服务器配置 (供MCP客户端使用)

MCP客户端需要以下JSON格式的配置信息来连接 'mcp-plex' 服务器并与之交互：

{
  "name": "Plex媒体智能助手",
  "command": "uv",
  "args": ["run", "mcp-server", "--transport", "stdio"],
  "description": "一个用于将Plex媒体库转换为LLM可查询数据库的MCP服务器，提供媒体搜索、推荐和播放控制功能。",
  "info": {
    "启动命令说明": "上述'command'和'args'组合起来执行'uv run mcp-server --transport stdio'，这是通过stdio传输协议启动mcp-plex服务器的默认方式。您需要确保'uv'工具已安装在服务器环境中，并且Plex及TMDb相关的环境变量已正确设置。",
    "可用命令行选项": [
      {
        "选项": "--transport",
        "可选值": ["stdio", "sse", "streamable-http"],
        "说明": "指定MCP服务器与客户端通信的传输协议。'stdio'是默认值，适用于本地或Docker容器内通信；'sse'通过Server-Sent Events提供HTTP流，适用于浏览器客户端；'streamable-http'提供普通流式HTTP响应。"
      },
      {
        "选项": "--bind",
        "说明": "当使用'sse'或'streamable-http'传输协议时，指定服务器绑定的IP地址，例如 '0.0.0.0' 表示监听所有可用接口。此参数不能与'stdio'同时使用。"
      },
      {
        "选项": "--port",
        "说明": "当使用'sse'或'streamable-http'传输协议时，指定服务器监听的端口号，例如 '8000'。此参数不能与'stdio'同时使用。"
      },
      {
        "选项": "--mount",
        "说明": "当使用'sse'或'streamable-http'传输协议时，指定服务器的URL路径前缀，例如 '/mcp'。此参数不能与'stdio'同时使用。"
      },
      {
        "选项": "--recommend-user",
        "说明": "可选。指定一个Plex用户名。当LLM请求媒体推荐时，服务器会自动排除该用户已观看过的媒体内容。这有助于避免推荐重复内容。例如：'JohnDoe'。"
      },
      {
        "选项": "--recommend-history-limit",
        "说明": "可选。与'--recommend-user'配合使用。限制服务器在获取用户观看历史时查询的条目数量（默认500条）。较小的数值可以减少Plex API的负载，但可能导致已观看内容被再次推荐。例如：'100'。"
      },
      {
        "选项": "--dense-model",
        "说明": "可选。指定用于生成密集向量嵌入的模型名称。默认使用'BAAI/bge-small-en-v1.5'。如果您有特定的嵌入模型需求，可以进行更改。例如：'my-custom-dense-model'。"
      },
      {
        "选项": "--sparse-model",
        "说明": "可选。指定用于生成稀疏向量嵌入的模型名称。默认使用'Qdrant/bm42-all-minilm-l6-v2-attentions'。与密集模型类似，可根据需要调整。例如：'my-custom-sparse-model'。"
      },
      {
        "选项": "--reranker-model",
        "说明": "可选。指定用于对搜索结果进行二次排序（reranking）的交叉编码器模型名称。默认使用'cross-encoder/ms-marco-MiniLM-L-6-v2'。如果追求更低延迟或没有GPU支持，可以考虑禁用重排序功能。"
      },
      {
        "选项": "--log-level",
        "说明": "可选。设置服务器运行时日志的详细程度。可选级别包括 'critical', 'error', 'warning', 'info', 'debug', 'notset'。默认级别为 'info'。例如：'debug'。"
      }
    ],
    "环境变量替代说明": "多数命令行参数也支持通过环境变量进行配置，环境变量的优先级高于命令行参数。例如，要通过SSE在端口8000上启动服务器并挂载到'/mcp'，您可以设置环境变量：'MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=8000 MCP_MOUNT=/mcp'，然后运行 'uv run mcp-server'。"
  }
}

基本使用方法

加载Plex元数据到Qdrant：
- 在启动MCP服务器之前，您需要将Plex媒体库的元数据加载到Qdrant向量数据库中。
- 加载示例数据（用于测试）： 如果您想使用项目提供的示例数据进行测试，可以运行：
```
uv run load-data --sample-dir sample-data
```
- 从Plex加载实时数据： 如果您已正确配置Plex的URL、Token和TMDb API Key（如安装步骤中所示），运行以下命令将从您的Plex服务器加载数据。此过程会自动处理IMDb查询和潜在的API限速重试：
```
uv run load-data
```
- 持续运行加载器（同步更新）： 您也可以让加载器持续运行，例如每600秒（10分钟）运行一次，以自动同步Plex媒体库的更新：
```
uv run load-data --continuous --delay 600
```
运行MCP服务器：
- 数据加载完成后，您可以通过以下命令启动MCP服务器：
```
uv run mcp-server
```
  - 请注意： 默认情况下，服务器通过stdio协议运行。如果您的MCP客户端需要HTTP/SSE连接，请参考“服务器配置”部分，添加 '--transport'、'--bind' 和 '--port' 等命令行参数或相应的环境变量。
- 服务器启动后，您的MCP客户端即可连接并开始通过MCP协议访问Plex媒体库的上下文信息和功能。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供MCP客户端使用)

基本使用方法

信息