moviefinder-mcp

Ein MCP-Server, der die API von The Movie Database (TMDB) umschließt. Erstellt mit @modelcontextprotocol/sdk und stdio-Transport.

Tools

Alle Tools geben zusammengefasstes JSON zurück (ID, Titel, Jahr, Übersicht, Bewertung, Poster-URL usw.) — die überflüssigen TMDB-Rohdaten werden entfernt.

Einrichtung

1. TMDB-API-Token abrufen

1. Erstellen Sie ein kostenloses Konto unter https://www.themoviedb.org/.

2. Besuchen Sie https://www.themoviedb.org/settings/api und kopieren Sie das API Read Access Token (v4). Dies ist ein langes JWT — es ist nicht der v3-API-Schlüssel.

2. Installieren und bauen

npm install
npm run build

3. Umgebung konfigurieren

Kopieren Sie .env.example nach .env und fügen Sie Ihr Token ein:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Server ausführen

npm start

Der Server kommuniziert über stdio mittels MCP und ist dafür gedacht, von einem MCP-Client (wie Claude Desktop) gestartet zu werden, nicht um interaktiv ausgeführt zu werden.

Registrierung bei Claude Desktop

Fügen Sie einen Eintrag in claude_desktop_config.json hinzu:

• 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": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

Starten Sie Claude Desktop nach dem Bearbeiten der Konfiguration neu. Die moviefinder-Tools erscheinen dann in jeder Unterhaltung.

Skripte

Fehlerbehandlung

Der Server gibt hilfreiche Meldungen für häufige TMDB-Fehler zurück:

• 401 — Token fehlt oder falscher Schlüsseltyp (muss ein v4 Read Access Token sein).

• 404 — der angeforderte Film / die Ressource existiert nicht.

• 429 — Ratenbegrenzung erreicht; der Retry-After-Wert wird einbezogen, falls vorhanden.

Hinweise

• Die Genre-Liste wird einmalig von /genre/movie/list abgerufen und im Arbeitsspeicher zwischengespeichert.

• Poster-URLs verwenden https://image.tmdb.org/t/p/w500.

• Keine Datenbank, kein Logging-Framework — beabsichtigt.