TMDB MCP-Server

Ein MCP-Server für die The Movie Database (TMDB) API. Er bietet Film- und TV-Suche, Streaming-Verfügbarkeit, Details zu Besetzung und Crew sowie Empfehlungen für Assistenten wie Codex und Claude Desktop.

Tools

Film-Entdeckung

• get_weekend_watchlist — Rangliste für das Wochenende nach Stimmung, Land, Sprache, Laufzeit, Bewertung und Diensten

• search_movies — Suche nach Titel/Schlagworten → Titel, IDs, Bewertungen, Zusammenfassungen

• get_trending — Top 10 der aktuell angesagten Filme (timeWindow: "day" | "week")

• get_weekly_trending_by_language — Wöchentlich angesagte Filme, gruppiert nach Originalsprache in Englisch, Hindi und Telugu

• search_by_genre — Filme nach Genre-Name, optionaler Jahresfilter

• advanced_search — Filtern nach Genre, Jahr, Mindestbewertung, Sortierung, Sprache

• search_by_keyword — Filme nach Thema/Schlagwort finden (z. B. "zombie", "heist")

Filmdetails

• get_movie_details — Vollständige Details: Besetzung, Crew, Laufzeit, Genres, Rezensionen (nach movieId)

• compare_movies — Direkter Vergleich von 2-5 Film-IDs mit Bewertungen, Laufzeit, Besetzung, Regisseur, Anbietern und Empfehlungsnotizen

• get_recommendations — Top 5 Empfehlungen basierend auf einer Film-ID

• get_similar_movies — Ähnliche Filme über den Ähnlichkeitsalgorithmus von TMDB

• get_watch_providers — Verfügbarkeit für Streaming/Verleih/Kauf nach Land (Standard: IN)

• find_where_to_watch — Suche nach 1-5 Filmtiteln und Rückgabe der Verfügbarkeit für Streaming/Verleih/Kauf mit bevorzugten Diensten

TV-Serien

• search_tv_shows — TV-Serien nach Titel suchen

• get_trending_tv — Top 10 der aktuell angesagten TV-Serien (timeWindow: "day" | "week")

Personen

• search_person — Schauspieler, Regisseure, Crew nach Namen finden → ID + bekannte Werke

• get_person_details — Vollständige Biografie + Filmografie (Filme + TV) nach personId

Ressourcen

• tmdb:///movie/<id> — Vollständige Filmdetails im JSON-Format (Titel, Besetzung, Regisseur, Rezensionen, Poster-URL)

Related MCP server: Usher MCP

Schnellstart

1. Holen Sie sich einen TMDB-API-Schlüssel unter themoviedb.org → Kontoeinstellungen → API

2. Klonen, installieren und bauen:

   git clone https://github.com/Laksh-star/mcp-server-tmdb.git
   cd mcp-server-tmdb
   npm install

3. Erstellen Sie eine lokale env-Datei und fügen Sie Ihren TMDB-Schlüssel hinzu:

   cp .env.example .env

4. Installieren Sie die lokale Codex- und Claude Desktop-Integration:

   npm run install:local

5. Starten Sie Codex oder Claude Desktop neu, falls diese bereits geöffnet sind.

6. Überprüfen Sie es mit einer Eingabeaufforderung wie:

   What movies are trending this week?

In Codex sollte eine neue Sitzung TMDB in der Plugin-Liste anzeigen und den mcp__tmdb__-Namensraum bereitstellen.

Tool-Oberflächen-Rauchtest

Verwenden Sie diesen Rauchtest nach dem Hinzufügen oder Zusammenführen von Tools. Er überprüft den erwarteten MCP-Tool-Vertrag und ruft die Haupt-Workflow-Tools auf: compare_movies, find_where_to_watch und get_weekend_watchlist.

Lokales stdio MCP:

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

Cloudflare-gehostetes MCP:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/tool-surface-smoke.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Das Skript schreibt ein kompaktes Verifizierungsartefakt nach:

examples/tool-surface-smoke.md

Um Tool-Überladung zu vermeiden, bevorzugen Sie Workflow-Tools, die mehrere TMDB-Aufrufe zu einer nützlichen Benutzerentscheidung kombinieren. Behalten Sie rohe Endpunkt-Tools nur bei, wenn sie breit wiederverwendbare Primitive sind.

Demo für wöchentlich angesagte Sprachen

Dieses Repo enthält eine kleine teilbare Demo, die das MCP-Tool get_weekly_trending_by_language aufruft. Es ruft live die wöchentlich angesagten TMDB-Filme ab und gruppiert die aktuelle erste Seite nach der TMDB-original_language.

Führen Sie es gegen den lokalen stdio MCP-Server aus:

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-trending

Nach der Bereitstellung dieser Version des Workers führen Sie dieselbe Demo gegen einen Remote-MCP-Endpunkt aus:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Wenn die Bereitstellung absichtlich ohne Authentifizierung für persönliche Tests erfolgt, lassen Sie TMDB_MCP_ACCESS_TOKEN weg.

Remote-MCP auf Cloudflare Workers

Dieses Repo kann auch als Remote-MCP-Server auf Cloudflare Workers ausgeführt werden. Der Remote-Server stellt dieselben TMDB-Tools unter /mcp über Streamable HTTP bereit, sodass Claude, Cowork, Claude Desktop-Connectoren und andere Remote-MCP-Clients eine Verbindung zu einer öffentlichen URL herstellen können.

Der bestehende lokale stdio-Server bleibt für Codex und die lokale Nutzung von Claude Desktop unverändert. Der Cloudflare-Einstiegspunkt ist src/worker.ts.

Der Worker stellt auch eine Browser-Demo unter / bereit: Weekend Watch Concierge. Er fragt nach Stimmung, Land, Sprache, Laufzeit, Bewertung und Streaming-Diensten und erstellt dann eine bewertete Film-Kurzliste unter Verwendung von TMDB-Entdeckung, Trends, aktuellen Kinofilmen, Credits, Postern und Daten der Watch-Anbieter.

Die Browser-Demo enthält auch ein MCP-Tool-Oberflächenpanel, das die bereitgestellte /mcp-Route aufruft, den erwarteten Tool-Vertrag überprüft und compare_movies, find_where_to_watch sowie get_weekend_watchlist stichprobenartig testet.

Für die vollständige Browser-App, den bereitgestellten Worker, den Zugriffstoken und die MCP-Übergabe siehe docs/weekend-watch-concierge.md.

Bereitstellung

1. Melden Sie sich bei Cloudflare an:

   npx wrangler login

2. Speichern Sie Ihren TMDB-Schlüssel als Worker-Geheimnis:

   npx wrangler secret put TMDB_API_KEY

3. Speichern Sie einen Zugriffstoken als Worker-Geheimnis, bevor Sie die Bereitstellung teilen:

   npx wrangler secret put ACCESS_TOKEN

   Wenn ACCESS_TOKEN gesetzt ist, erfordern POST /api/concierge und POST /mcp:

   Authorization: Bearer <your-access-token>

4. Überprüfen Sie das Worker-Bundle:

   npm run worker:dry-run

5. Bereitstellen:

   npm run worker:deploy

Cloudflare gibt eine URL aus wie:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev

Verwenden Sie diesen MCP-Endpunkt in Remote-Clients:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Verwenden Sie diese Browser-Demo-URL:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/

Verbindung von Claude / Cowork

Für benutzerdefinierte Claude-Connectoren:

1. Öffnen Sie die Claude-Einstellungen: Customize -> Connectors.

2. Klicken Sie auf + -> Add custom connector.

3. Verwenden Sie die bereitgestellte Worker-MCP-URL:

   https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

4. Aktivieren Sie den Connector in einer Konversation und stellen Sie eine TMDB-Frage, wie zum Beispiel:

   What movies are trending this week?

Für Claude Desktop-Versionen oder MCP-Clients, die noch einen lokalen Befehl erfordern, verwenden Sie den mcp-remote-Proxy:

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

Sicherheitshinweis

Wenn ACCESS_TOKEN nicht konfiguriert ist, ist der Worker für einfache persönliche Tests ohne Authentifizierung. Jeder, der die Worker-URL hat, kann die schreibgeschützten TMDB-Tools aufrufen und Ihr TMDB-API-Kontingent verbrauchen. Halten Sie ACCESS_TOKEN konfiguriert oder verwenden Sie Cloudflare Access, bevor Sie dies über Ihre eigenen Konten hinaus teilen.

Weekend Watch Concierge

Führen Sie den Offline-Concierge-Test aus:

npm test

Dies baut das TypeScript-Projekt, startet einen kleinen lokalen TMDB-kompatiblen Fixture-Server und überprüft, ob createWeekendConcierge eine angeforderte Übereinstimmung mit dem Streaming-Dienst an erster Stelle einstuft, während der Laufzeitfilter respektiert wird. Es wird kein TMDB-API-Schlüssel benötigt.

Führen Sie den Worker lokal aus:

npm run worker:dev

Dies synchronisiert lokale Werte aus .env in eine nicht verfolgte .dev.vars-Datei, damit Wrangler TMDB_API_KEY während der lokalen Entwicklung für den Worker bereitstellen kann.

Für geschützte lokale Tests fügen Sie ACCESS_TOKEN zu .env hinzu. Die Browser-App verfügt über ein Zugriffstoken-Feld und die Rauchtest-Skripte können ACCESS_TOKEN oder TMDB_MCP_ACCESS_TOKEN aus der Shell-Umgebung lesen.

Öffnen:

http://127.0.0.1:8787/

Rauchtest der Concierge-API, nachdem der lokale Worker läuft:

npm run smoke:concierge

Rauchtest des Remote-MCP-Endpunkts und Aufruf des Agenten-Concierge-Tools:

node scripts/remote-mcp-smoke.mjs http://127.0.0.1:8787/mcp --call-concierge

Für eine geschützte Bereitstellung:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

Oder testen Sie einen bereitgestellten Worker:

node scripts/concierge-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev

Die App verwendet:

• POST /api/concierge für bewertete Filmempfehlungen

• GET /health für den Bereitstellungsstatus

• POST /mcp für Remote-MCP-Clients

Agenten können get_weekend_watchlist aufrufen mit:

• mood: crowd, thriller, thoughtful, funny, family oder mindbend

• country: Watch-Provider-Region, zum Beispiel IN oder US

• language: Originalsprachencode, zum Beispiel en, hi, ta, te oder any

• runtime: maximale Minuten, zum Beispiel 120, 150 oder any

• minRating: minimale TMDB-Bewertung

• services: bevorzugte Streaming-Dienste

Cloudflare MCP-Demo-Workflow

Für einen konkreten End-to-End-Agenten-Workflow führen Sie die "Now-Playing"-Folgedemo aus. Sie verwendet den MCP-Server so, wie es ein Remote-Client tun würde:

1. get_now_playing für die aktuelle Kino-Entdeckung in einer ausgewählten Region

2. get_movie_details für den ausgewählten Titel

3. get_watch_providers für die "Jetzt ansehen"-Verfügbarkeit

4. get_recommendations, mit get_similar_movies-Fallback für sehr neue Titel

5. get_watch_providers für weitere Verfügbarkeitsprüfungen

Lokales stdio MCP:

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

Cloudflare-gehostetes MCP:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/now-playing-follow-on-demo.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --region US

Das Skript schreibt das endgültige Artefakt hierhin:

examples/now-playing-follow-on-demo.md

Was npm run install:local tut

Das Installationsprogramm verwendet den repo-eigenen Launcher unter plugins/tmdb/scripts/run-server.sh.

Für Codex:

• Registriert den Launcher als MCP-Server

• Installiert ein lokales TMDB-Plugin-Payload, damit es in der Plugin-UI erscheint

Für Claude Desktop:

• Registriert denselben Launcher als lokalen MCP-Server

Es aktualisiert:

• ~/.codex/config.toml

• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json

• ~/.codex/plugins/cache/openai-curated/tmdb/...

• ~/Library/Application Support/Claude/claude_desktop_config.json

Der Launcher liest TMDB_API_KEY aus Ihrer Shell-Umgebung oder aus der Repo-.env-Datei.

Verwendung mit Claude Desktop

Wenn Sie eine manuelle Einrichtung bevorzugen, fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

Starten Sie Claude Desktop nach dem Bearbeiten der Konfiguration neu.

Verwendung mit Codex

Das Installationsprogramm fügt diese Blöcke zu ~/.codex/config.toml hinzu:

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

Starten Sie Codex nach dem Bearbeiten der Konfiguration neu. In einer neuen Codex-Sitzung sollte TMDB in der Plugin-Liste erscheinen und den mcp__tmdb__-Namensraum beisteuern.

Validierung

Offline-Rauchtest:

TMDB_API_KEY=dummy node plugins/tmdb/scripts/smoke-test.mjs

Online-Rauchtest:

set -a && source ./.env && set +a && node plugins/tmdb/scripts/smoke-test.mjs --online

Plugin-Dokumentation

Für Plugin-Verpackung, lokales Installationsverhalten und Codex-spezifische Hinweise siehe plugins/tmdb/README.md.

Verwendung mit BizClaw / NanoClaw

In den Agenten-Container integriert. Setzen Sie einfach TMDB_API_KEY in Ihrer .env-Datei — keine Konfiguration erforderlich.

Beispiel-Prompts

"What's trending in movies this week?"
"Find me Thriller movies from 2023"
"Who is Christopher Nolan and what has he directed?"
"Where can I watch Inception in India?"
"Get details for movie ID 550 (Fight Club)"
"Find movies similar to Interstellar"
"What are the trending TV shows right now?"

Lizenz

MIT