Plex MCP Server

Сервер Model Context Protocol (MCP), который предоставляет ИИ-ассистентам комплексный доступ к вашим Plex Media Server, Sonarr, Radarr и Trakt.tv — всё с одного унифицированного сервера.

Что это такое?

Этот MCP-сервер превращает ваш Plex Media Server в базу данных, доступную для запросов ИИ. Задавайте своему ИИ-ассистенту такие вопросы, как:

• «Какие фильмы я смотрел недавно?»

• «Покажи мою статистику просмотров за последний месяц»

• «Какой контент на моем сервере самый популярный?»

• «Найди боевики в моей библиотеке»

• «Что у меня в списке продолжения просмотра?»

• «Добавь это новое шоу в Sonarr»

• «Что у меня в очереди на загрузку?»

• «Синхронизируй мою историю просмотров с Trakt»

• «Порекомендуй мне фильмы, которые я еще не видел»

Related MCP server: YARR Media Stack MCP Server

Возможности

45 инструментов «из коробки» (54 с включенными операциями записи):

• Управление библиотекой Plex — просмотр библиотек, поиск медиа, получение подробных метаданных, списки воспроизведения и список отслеживания.

• Аналитика в стиле Tautulli — статистика просмотров, активность пользователей, популярный контент, история просмотров.

• Персонализированные рекомендации — ИИ-рекомендации фильмов на основе вашей истории просмотров, жанров, режиссеров и актеров. Поддерживает профили для каждого пользователя на серверах Plex с несколькими пользователями.

• Интеграция с Sonarr/Radarr — просмотр, поиск, добавление сериалов/фильмов, просмотр очередей, запуск загрузок.

• Синхронизация с Trakt.tv — OAuth-аутентификация, синхронизация истории просмотров, расширенная статистика, скробблинг. При настройке данные Trakt обогащают рекомендации, учитывая фильмы, просмотренные вне Plex.

• Операции записи (по выбору) — создание/редактирование списков воспроизведения, обновление метаданных, управление списком отслеживания.

Один сервер, все инструменты. Учетные данные Trakt и Sonarr/Radarr необязательны — инструменты, которым они нужны, вернут полезное сообщение о настройке, если ключ отсутствует. Вам не нужно настраивать всё сразу.

Быстрый старт

Предварительные требования

• Node.js 20+

• Plex Media Server (любая актуальная версия)

• Токен Plex (Как получить ваш токен)

• MCP-совместимый клиент (Claude Desktop и т.д.)

Установка

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Или установите напрямую из npm:

npx plex-mcp-server

Конфигурация

1. Получите ваш токен Plex (см. инструкции ниже)

2. Настройте ваш MCP-клиент (например, Claude Desktop):

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-mcp-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

Требуется только PLEX_TOKEN. Все остальные учетные данные необязательны — инструменты для ненастроенных сервисов вернут понятное сообщение об ошибке с объяснением, как их настроить, вместо того чтобы аварийно завершать работу сервера.

API-ключи Sonarr/Radarr можно найти в разделе Settings > General > API Key в веб-интерфейсе каждого приложения.

Настройка Trakt.tv требует приложения Trakt OAuth. Создайте его с URI перенаправления urn:ietf:wg:oauth:2.0:oob, затем добавьте Client ID и Secret в вашу конфигурацию. Как только сервер будет запущен, попросите вашего ИИ-ассистента «аутентифицироваться в Trakt» — он проведет вас через процесс OAuth. Подробные инструкции см. в руководстве по настройке Trakt.

В v1.0.x было три отдельных серверных бинарных файла (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). В v1.1.0+ они заменены одним унифицированным бинарным файлом: build/plex-mcp-server.js.

Старые бинарные файлы все еще работают, но выдают предупреждение об устаревании. Обновите вашу конфигурацию MCP, чтобы она указывала на build/plex-mcp-server.js, и удалите все дублирующиеся записи серверов.

Полную информацию см. в руководстве по миграции.

Использование

После настройки вы можете спросить своего ИИ-ассистента:

"What movies did I watch last week?"
"Show me my most popular TV shows this month"
"Give me viewing statistics for the past 30 days"
"Search for Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

Рекомендуемые рабочие процессы

Синхронизация истории просмотров Plex с Trakt:

1. Настройте учетные данные Trakt (см. выше)

2. Спросите: «Authenticate with Trakt» — следуйте процессу OAuth

3. Спросите: «Do a dry run sync of my Plex history to Trakt» — предварительный просмотр того, что будет синхронизировано

4. Спросите: «Sync my Plex watch history to Trakt» — запустите фактическую синхронизацию

Поиск и добавление нового контента:

1. Спросите: «Search Sonarr for The Beverly Hillbillies» — найдите TVDB ID

2. Спросите: «Add The Beverly Hillbillies to Sonarr» — он автоматически определит профили качества и корневые папки

3. Спросите: «What's in my Sonarr download queue?» — отслеживайте прогресс

Получение персонализированных рекомендаций:

1. Спросите: «Recommend me some movies from my library»

2. Движок анализирует вашу историю просмотров — жанры, режиссеров, актеров, рейтинги

3. Оценивает каждый непросмотренный фильм и возвращает лучшие совпадения с причинами

4. Для серверов с несколькими пользователями укажите пользователя: «Recommend movies for Titus»

5. Если настроен Trakt, он автоматически использует и вашу историю Trakt — учитывая фильмы, которые вы смотрели вне Plex (на других платформах, до того как была настроена отслеживание)

Кроссплатформенная аналитика просмотров:

1. Спросите: «Show me my Plex viewing stats for the last 30 days»

2. Спросите: «What are my Trakt stats?» — посмотрите пожизненную статистику (просмотренные фильмы, часы, вехи)

3. Спросите: «What are my most popular movies this month?»

Доступные функции

Инструменты Plex (19 инструментов)

Операции записи (9 инструментов, по выбору)

Установите PLEX_ENABLE_MUTATIVE_OPS=true, чтобы включить эти инструменты. Они позволяют вашему ИИ-ассистенту вносить изменения на ваш сервер Plex. Используйте с осторожностью — хотя мы тестируем эти инструменты, гарантий нет. Проверяйте изменения, которые предлагает ваш ассистент, перед подтверждением.

Инструменты Sonarr (8 инструментов)

Инструменты Radarr (8 инструментов)

Кросс-сервисные инструменты (1 инструмент)

Инструменты Trakt (9 инструментов)

Получение вашего токена Plex

1. Откройте веб-приложение Plex в браузере

2. Перейдите в Settings > Account > Privacy

3. Нажмите "Show Advanced" внизу

4. Скопируйте ваш токен Plex

Альтернативный метод:

• Посетите: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account

• Найдите поле "Plex Token"

Структура проекта

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (17 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

Разработка

Скрипты

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

Сборка из исходного кода

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

Вклад в проект

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request. Для серьезных изменений, пожалуйста, сначала откройте issue, чтобы обсудить, что вы хотите изменить.

Руководство по разработке

1. Сделайте форк репозитория

2. Создайте ветку для функции (git checkout -b feature/amazing-feature)

3. Закоммитьте изменения (git commit -m 'Add amazing feature')

4. Отправьте в ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

Устранение неполадок

Распространенные проблемы

Connection refused:

• Убедитесь, что ваш сервер Plex запущен

• Проверьте PLEX_URL в конфигурации среды

• Убедитесь, что порт (обычно 32400) правильный

Ошибки аутентификации:

• Убедитесь, что ваш токен Plex правильный

• Проверьте разрешения токена в настройках Plex

• Убедитесь, что срок действия токена не истек

Пустые ответы:

• Некоторые функции требуют Plex Pass

• Проверьте, доступны ли ваши библиотеки

• Убедитесь, что медиафайлы были просканированы и доступны

Проблемы с подключением Sonarr/Radarr:

• Убедитесь, что Sonarr/Radarr запущен и доступен с хоста MCP-сервера

• Проверьте прави