moviefinder-mcp

Un servidor MCP que envuelve la API de TMDB para que un cliente compatible con MCP (Claude Desktop, Claude Code, etc.) pueda buscar películas y programas de televisión, consultar detalles, ver qué es tendencia, obtener recomendaciones y comprobar dónde se emite un título.

Herramientas

Herramienta	Descripción
`search_movies`	Buscar películas por título; `year` opcional.
`search_tv`	Buscar programas de televisión por nombre.
`get_movie_details`	Detalles de la película con reparto, director y URL del tráiler.
`get_recommendations`	Recomendaciones de TMDB para un ID de película.
`get_similar`	Películas similares a un ID de película.
`get_trending`	Tendencias de `movie` / `tv` / `all` por `day` o `week`.
`where_to_stream`	Proveedores de visualización (streaming / alquiler / compra) por país (por defecto `US`).
`discover_movies`	Descubrir por nombre de `genre`, `min_rating`, `year`, `sort_by`.

Todas las herramientas devuelven JSON resumido (id, título, año, resumen, calificación, URL del póster, además de campos específicos de la herramienta) en lugar de cargas útiles de TMDB sin procesar.

Configuración

Requisitos: 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

Obtención de una clave de API de TMDB

Crea una cuenta de TMDB en https://www.themoviedb.org/.
Abre https://www.themoviedb.org/settings/api.
Copia el API Read Access Token (v4 auth) — no la clave de API v3.
Ponla en .env como TMDB_API_KEY=....

El servidor la envía como Authorization: Bearer <token>.

Registro en Claude Desktop

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

Reinicia Claude Desktop. Las herramientas anteriores aparecerán bajo el servidor moviefinder.

Notas

La lista de géneros (/genre/movie/list) se obtiene una vez y se almacena en caché en la memoria para discover_movies.
Las respuestas 401 / 404 / 429 se muestran con mensajes procesables.
Las entradas se validan con zod antes de cualquier llamada a TMDB.