moviefinder-mcp

Un servidor MCP que envuelve la API de The Movie Database (TMDB). Construido con @modelcontextprotocol/sdk y transporte stdio.

Herramientas

Todas las herramientas devuelven JSON resumido (id, título, año, resumen, calificación, URL del póster, etc.); los campos crudos y ruidosos de TMDB se eliminan.

Configuración

1. Obtener un token de API de TMDB

1. Crea una cuenta gratuita en https://www.themoviedb.org/.

2. Visita https://www.themoviedb.org/settings/api y copia el API Read Access Token (v4). Este es un JWT largo; no es la clave de API v3.

2. Instalar y compilar

npm install
npm run build

3. Configurar el entorno

Copia .env.example a .env y pega tu token:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Ejecutar el servidor

npm start

El servidor utiliza MCP sobre stdio y está destinado a ser iniciado por un cliente MCP (como Claude Desktop), no para ejecutarse de forma interactiva.

Registrar en Claude Desktop

Añade una entrada a 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": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

Reinicia Claude Desktop después de editar la configuración. Las herramientas de moviefinder aparecerán entonces en cualquier conversación.

Scripts

Manejo de errores

El servidor devuelve mensajes útiles para fallos comunes de TMDB:

• 401 — falta el token o el tipo de clave es incorrecto (debe ser un token de acceso de lectura v4).

• 404 — la película / recurso solicitado no existe.

• 429 — límite de tasa alcanzado; el valor Retry-After se incluye cuando está presente.

Notas

• La lista de géneros se obtiene una vez desde /genre/movie/list y se almacena en caché en la memoria.

• Las URLs de los pósteres usan https://image.tmdb.org/t/p/w500.

• Sin base de datos, sin marco de registro (logging) — por diseño.