Plex MCP Server

Ein Model Context Protocol (MCP)-Server, der KI-Assistenten umfassenden Zugriff auf Ihren Plex Media Server, Sonarr, Radarr und Trakt.tv bietet – alles über einen einzigen, vereinheitlichten Server.

Was ist das?

Dieser MCP-Server verwandelt Ihren Plex Media Server in eine KI-abfragbare Datenbank. Stellen Sie Ihrem KI-Assistenten Fragen wie:

• "Welche Filme habe ich kürzlich angesehen?"

• "Zeige mir meine Wiedergabestatistiken für den letzten Monat"

• "Was sind die beliebtesten Inhalte auf meinem Server?"

• "Finde Actionfilme in meiner Bibliothek"

• "Was steht auf meiner 'Weiter ansehen'-Liste?"

• "Füge diese neue Serie zu Sonarr hinzu"

• "Was befindet sich in meiner Download-Warteschlange?"

• "Synchronisiere meinen Wiedergabeverlauf mit Trakt"

• "Empfiehl mir einige Filme, die ich noch nicht gesehen habe"

Related MCP server: YARR Media Stack MCP Server

Funktionen

45 Tools direkt einsatzbereit (54 mit aktivierten Schreiboperationen):

• Plex-Bibliotheksverwaltung — Bibliotheken durchsuchen, Medien finden, detaillierte Metadaten abrufen, Wiedergabelisten und Merklisten auflisten

• Tautulli-ähnliche Analysen — Wiedergabestatistiken, Benutzeraktivität, beliebte Inhalte, Wiedergabeverlauf

• Personalisierte Empfehlungen — KI-gestützte Filmvorschläge basierend auf Ihrem Wiedergabeverlauf, Genres, Regisseuren und Schauspielern. Unterstützt Benutzerprofile für Plex-Server mit mehreren Benutzern.

• Sonarr/Radarr-Integration — Serien/Filme durchsuchen, finden und hinzufügen, Warteschlangen anzeigen, Downloads auslösen

• Trakt.tv-Synchronisierung — OAuth-Authentifizierung, Synchronisierung des Wiedergabeverlaufs, erweiterte Statistiken, Scrobbling. Wenn konfiguriert, reichern Trakt-Daten die Empfehlungen an, indem sie Filme erfassen, die außerhalb von Plex angesehen wurden.

• Schreiboperationen (Opt-in) — Wiedergabelisten erstellen/bearbeiten, Metadaten aktualisieren, Merklisten verwalten

Ein Server, alle Tools. Trakt- und Sonarr/Radarr-Anmeldedaten sind optional – Tools, die diese benötigen, geben eine hilfreiche Einrichtungsnachricht aus, falls der Schlüssel fehlt. Sie müssen nicht alles im Voraus konfigurieren.

Schnellstart

Voraussetzungen

• Node.js 20+

• Plex Media Server (jede aktuelle Version)

• Plex-Token (Wie Sie Ihren Token erhalten)

• MCP-kompatibler Client (Claude Desktop, etc.)

Installation

# 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

Oder installieren Sie direkt über npm:

npx plex-mcp-server

Konfiguration

1. Holen Sie sich Ihren Plex-Token (siehe Anweisungen unten)

2. Konfigurieren Sie Ihren MCP-Client (z. B. 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"
      }
    }
  }
}

Nur PLEX_TOKEN ist erforderlich. Alle anderen Anmeldedaten sind optional – Tools für nicht konfigurierte Dienste geben eine klare Fehlermeldung aus, die erklärt, wie sie eingerichtet werden, anstatt den Server zum Absturz zu bringen.

Sonarr/Radarr-API-Schlüssel finden Sie unter Einstellungen > Allgemein > API-Schlüssel in der Web-Benutzeroberfläche der jeweiligen App.

Die Trakt.tv-Einrichtung erfordert eine Trakt OAuth-Anwendung. Erstellen Sie eine mit dem Redirect-URI urn:ietf:wg:oauth:2.0:oob und fügen Sie dann die Client-ID und das Secret zu Ihrer Konfiguration hinzu. Sobald der Server läuft, bitten Sie Ihren KI-Assistenten, sich "mit Trakt zu authentifizieren" – er führt Sie durch den OAuth-Prozess. Siehe den Trakt-Einrichtungsleitfaden für detaillierte Anweisungen.

In v1.0.x gab es drei separate Server-Binärdateien (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). In v1.1.0+ werden diese durch eine einzige vereinheitlichte Binärdatei ersetzt: build/plex-mcp-server.js.

Die alten Binärdateien funktionieren weiterhin, geben aber eine Veraltungswarnung aus. Aktualisieren Sie Ihre MCP-Konfiguration, um auf build/plex-mcp-server.js zu verweisen, und entfernen Sie alle doppelten Servereinträge.

Siehe den Migrationsleitfaden für vollständige Details.

Verwendung

Sobald die Konfiguration abgeschlossen ist, können Sie Ihren KI-Assistenten fragen:

"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"

Empfohlene Arbeitsabläufe

Plex-Wiedergabeverlauf mit Trakt synchronisieren:

1. Trakt-Anmeldedaten einrichten (siehe oben)

2. Fragen: "Authentifiziere dich mit Trakt" – folgen Sie dem OAuth-Prozess

3. Fragen: "Führe einen Testlauf der Synchronisierung meines Plex-Verlaufs mit Trakt durch" – sehen Sie eine Vorschau dessen, was synchronisiert würde

4. Fragen: "Synchronisiere meinen Plex-Wiedergabeverlauf mit Trakt" – führen Sie die tatsächliche Synchronisierung aus

Neue Inhalte finden und hinzufügen:

1. Fragen: "Suche in Sonarr nach The Beverly Hillbillies" – finden Sie die TVDB-ID

2. Fragen: "Füge The Beverly Hillbillies zu Sonarr hinzu" – es erkennt automatisch Qualitätsprofile und Stammordner

3. Fragen: "Was befindet sich in meiner Sonarr-Download-Warteschlange?" – Fortschritt überwachen

Personalisierte Empfehlungen erhalten:

1. Fragen: "Empfiehl mir einige Filme aus meiner Bibliothek"

2. Die Engine analysiert Ihren Wiedergabeverlauf – Genres, Regisseure, Schauspieler, Bewertungen

3. Bewertet jeden ungesehenen Film und gibt die besten Übereinstimmungen mit Begründungen zurück

4. Geben Sie bei Servern mit mehreren Benutzern den Benutzer an: "Empfiehl Filme für Titus"

5. Wenn Trakt konfiguriert ist, verwendet es automatisch auch Ihren Trakt-Verlauf – und erfasst Filme, die Sie außerhalb von Plex angesehen haben (andere Plattformen, bevor das Tracking eingerichtet wurde)

Plattformübergreifende Wiedergabeanalysen:

1. Fragen: "Zeige mir meine Plex-Wiedergabestatistiken für die letzten 30 Tage"

2. Fragen: "Was sind meine Trakt-Statistiken?" – sehen Sie lebenslange Statistiken (angesehene Filme, Stunden, Meilensteine)

3. Fragen: "Was sind meine beliebtesten Filme diesen Monat?"

Verfügbare Funktionen

Plex-Tools (19 Tools)

Schreiboperationen (9 Tools, Opt-in)

Setzen Sie PLEX_ENABLE_MUTATIVE_OPS=true, um diese Tools zu aktivieren. Sie ermöglichen es Ihrem KI-Assistenten, Änderungen an Ihrem Plex-Server vorzunehmen. Mit Vorsicht verwenden – obwohl wir diese Tools testen, gibt es keine Garantien. Überprüfen Sie die Änderungen, die Ihr Assistent vorschlägt, bevor Sie sie bestätigen.

Sonarr-Tools (8 Tools)

Radarr-Tools (8 Tools)

Dienstübergreifende Tools (1 Tool)

Trakt-Tools (9 Tools)

Ihren Plex-Token erhalten

1. Öffnen Sie die Plex Web App in Ihrem Browser

2. Navigieren Sie zu Einstellungen > Konto > Datenschutz

3. Klicken Sie unten auf "Erweitert anzeigen"

4. Kopieren Sie Ihren Plex-Token

Alternative Methode:

• Besuchen Sie: http://IHR_PLEX_IP:32400/web/index.html#!/settings/account

• Suchen Sie nach dem Feld "Plex-Token"

Projektstruktur

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

Entwicklung

Skripte

# 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

Aus Quellcode bauen

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

Mitwirken

Beiträge sind willkommen! Bitte fühlen Sie sich frei, einen Pull Request einzureichen. Bei größeren Änderungen eröffnen Sie bitte zuerst ein Issue, um zu besprechen, was Sie ändern möchten.

Entwicklungsrichtlinien

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Commiten Sie Ihre Änderungen (git commit -m 'Add amazing feature')

4. Pushen Sie auf den Branch (git push origin feature/amazing-feature)

5. Öffnen Sie einen Pull Request

Fehlerbehebung

Häufige Probleme

Verbindung verweigert:

• Überprüfen Sie, ob Ihr Plex-Server läuft

• Überprüfen Sie die PLEX_URL in Ihrer Umgebungskonfiguration

• Stellen Sie sicher, dass der Port (normalerweise 32400) korrekt ist

Authentifizierungsfehler:

• Überprüfen Sie, ob Ihr Plex-Token korrekt ist

• Überprüfen Sie die Token-Berechtigungen in den Plex-Einstellungen

• Stellen Sie sicher, dass der Token nicht abgelaufen ist

Leere Antworten:

• Einige Funktionen erfordern Plex Pass

• Überprüfen Sie, ob Ihre Bibliotheken zugänglich sind

• Stellen Sie sicher, dass die