moviefinder-mcp

Ein MCP-Server, der die TMDB-API umschließt, sodass ein MCP-fähiger Client (Claude Desktop, Claude Code usw.) nach Filmen und TV-Sendungen suchen, Details nachschlagen, Trends finden, Empfehlungen erhalten und prüfen kann, wo ein Titel gestreamt wird.

Tools

Tool	Beschreibung
`search_movies`	Suche nach Filmen nach Titel; optional `year`.
`search_tv`	Suche nach TV-Sendungen nach Name.
`get_movie_details`	Filmdetails mit Besetzung, Regisseur und Trailer-URL.
`get_recommendations`	TMDB-Empfehlungen für eine Film-ID.
`get_similar`	Filme, die einer Film-ID ähnlich sind.
`get_trending`	Trend-`movie` / `tv` / `all` für `day` oder `week`.
`where_to_stream`	Streaming-Anbieter (Stream / Leihen / Kaufen) nach Land (Standard `US`).
`discover_movies`	Entdecken nach `genre`-Name, `min_rating`, `year`, `sort_by`.

Alle Tools geben zusammengefasstes JSON (ID, Titel, Jahr, Übersicht, Bewertung, Poster-URL sowie tool-spezifische Felder) anstelle von rohen TMDB-Payloads zurück.

Einrichtung

Voraussetzungen: Node 20+.

npm install
cp .env.example .env
# edit .env and paste your TMDB v4 read access token
npm run build
npm start    # runs the compiled server over stdio

Erhalt eines TMDB-API-Schlüssels

Erstellen Sie ein TMDB-Konto unter https://www.themoviedb.org/.
Öffnen Sie https://www.themoviedb.org/settings/api.
Kopieren Sie das API Read Access Token (v4 auth) — nicht den v3-API-Schlüssel.
Fügen Sie es in .env als TMDB_API_KEY=... ein.

Der Server sendet es als Authorization: Bearer <token>.

Registrierung bei Claude Desktop

Bearbeiten Sie claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "your_v4_read_access_token_here"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die oben genannten Tools erscheinen unter dem moviefinder-Server.

Hinweise

Die Genre-Liste (/genre/movie/list) wird einmal abgerufen und für discover_movies im Arbeitsspeicher zwischengespeichert.
401 / 404 / 429-Antworten werden mit umsetzbaren Meldungen angezeigt.
Eingaben werden vor jedem TMDB-Aufruf mit zod validiert.