TMDB MCP-Server

Ein MCP-Server für die API von The Movie Database (TMDB). Er bietet Funktionen zur Suche nach Filmen und TV-Sendungen, Informationen zur Verfügbarkeit bei Streaming-Diensten, Details zu Besetzung und Crew sowie Empfehlungen für Assistenten wie Codex und Claude Desktop.

Tools

Filmentdeckung

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

• search_by_genre — Filme nach Genre-Name, optionaler Filter nach Jahr

• 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)

• 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)

TV-Sendungen

• search_tv_shows — Suche nach TV-Serien nach Titel

• get_trending_tv — Top 10 der aktuell angesagten TV-Sendungen (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: TMDB MCP Server

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 in einer neuen Sitzung TMDB in der Plugin-Liste erscheinen und den mcp__tmdb__-Namensraum bereitstellen.

Remote-MCP auf Cloudflare Workers

Dieses Repository 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 die Verwendung mit Codex und lokalem Claude Desktop unverändert. Der Cloudflare-Einstiegspunkt ist src/worker.ts.

Der Worker bietet außerdem eine Browser-Demo unter / an: 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, aktuell laufenden Filmen, Credits, Postern und Daten zu Streaming-Anbietern.

Für die vollständige Browser-App, den bereitgestellten Worker, das 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 ein Zugriffstoken als Worker-Geheimnis, bevor Sie die Bereitstellung teilen:

   npx wrangler secret put ACCESS_TOKEN

   Wenn ACCESS_TOKEN festgelegt 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 Unterhaltung und stellen Sie eine TMDB-Frage, wie zum Beispiel:

   What movies are trending this week?

Für Claude Desktop-Versionen oder MCP-Clients, die weiterhin 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 zugänglich. Jeder, der die Worker-URL hat, kann die schreibgeschützten TMDB-Tools aufrufen und Ihr TMDB-API-Kontingent verbrauchen. Lassen Sie ACCESS_TOKEN konfiguriert oder verwenden Sie Cloudflare Access, bevor Sie dies außerhalb Ihrer eigenen Konten teilen.

Weekend Watch Concierge

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 Feld für das Zugriffstoken, und die Smoke-Skripte können ACCESS_TOKEN oder TMDB_MCP_ACCESS_TOKEN aus der Shell-Umgebung lesen.

Öffnen:

http://127.0.0.1:8787/

Führen Sie einen Smoke-Test der Concierge-API durch, nachdem der lokale Worker läuft:

npm run smoke:concierge

Führen Sie einen Smoke-Test des Remote-MCP-Endpunkts durch und rufen Sie das agentenseitige Concierge-Tool auf:

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: Region des Streaming-Anbieters, zum Beispiel IN oder US

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

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

• minRating: minimale TMDB-Bewertung

• services: bevorzugte Streaming-Dienste

Was npm run install:local bewirkt

Das Installationsprogramm verwendet den im Repository enthaltenen Launcher unter plugins/tmdb/scripts/run-server.sh.

Für Codex:

• Registriert den Launcher als MCP-Server

• Installiert eine lokale TMDB-Plugin-Payload, damit es in der Plugin-Benutzeroberfläche 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 .env-Datei des Repositorys.

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-Smoke-Test:

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

Online-Smoke-Test:

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

Plugin-Dokumentation

Für Plugin-Paketierung, 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