TMDB MCP Server

Accede a información de películas, búsquedas y recomendaciones desde la API de The Movie Database (TMDB).

Documentación

Servidor MCP de TMDB

Un servidor MCP para la API de The Movie Database (TMDB). Proporciona búsqueda de películas y series, disponibilidad de streaming, detalles de reparto y equipo, y recomendaciones para asistentes como Codex y Claude Desktop.

Para la división de arquitectura entre el servidor MCP reutilizable y los flujos de trabajo de funciones de nivel superior, consulta USERGUIDE.md.

Herramientas

Descubrimiento de películas

get_weekend_watchlist — Lista corta clasificada para el fin de semana según estado de ánimo, país, idioma, duración, calificación y servicios
plan_watch_party — Plan grupal de noche de cine con una selección principal, respaldo, comodín, razones de ajuste al grupo, disponibilidad de proveedores y filtrado de títulos evitados
build_franchise_watch_order — Guía de franquicia/universo con orden de estreno, orden sugerido, duración total y notas según proveedor
build_collection_gap_plan — Plan de finalización de franquicia con entradas vistas/faltantes, duración restante, disponibilidad de proveedores y ruta de finalización
recommend_from_taste_profile — Recomendaciones basadas en títulos que gustan/no gustan con puntuación según proveedor, razones de coincidencia y advertencias
build_release_calendar_watchlist — Lista de seguimiento por ventana de estreno con próximos estrenos, selecciones listas para proveedores, líneas base para audiencias amplias y puntuación para ver más tarde
search_movies — Búsqueda por título/palabras clave → títulos, IDs, calificaciones, resúmenes
get_trending — Top 10 de películas en tendencia (timeWindow: "day" | "week")
get_weekly_trending_by_language — Películas en tendencia semanal agrupadas por idioma original en inglés, hindi y telugu
search_by_genre — Películas por nombre de género, con filtro opcional de año
advanced_search — Filtrar por género, año, calificación mínima, orden, idioma
search_by_keyword — Encontrar películas por tema/palabra clave (p. ej. "zombie", "atraco")

Detalles de películas

get_movie_details — Detalles completos: reparto, equipo, duración, géneros, reseñas (por movieId)
compare_movies — Comparación lado a lado para 2-5 IDs de películas con calificaciones, duración, reparto, director, proveedores y notas de mejor ajuste
get_recommendations — Top 5 de recomendaciones basadas en un ID de película
get_similar_movies — Películas similares mediante el algoritmo de similitud de TMDB
get_watch_providers — Disponibilidad de streaming/alquiler/compra por país (predeterminado: IN)
find_where_to_watch — Buscar 1-5 títulos de películas y devolver disponibilidad de streaming/alquiler/compra con coincidencias de servicios preferidos

Series de TV

search_tv_shows — Buscar series de TV por título
get_trending_tv — Top 10 de series de TV en tendencia (timeWindow: "day" | "week")

Personas

search_person — Encontrar actores, directores, equipo por nombre → ID + obras conocidas
get_person_details — Biografía completa + filmografía (películas + TV) por personId
build_person_watch_path — Ruta de seguimiento de actor/director con selecciones mejor calificadas, disponibles ahora, recientes y de inicio

Recursos

tmdb:///movie/<id> — Detalles completos de película en JSON (título, reparto, director, reseñas, URL del póster)

Inicio rápido

Obtén una clave de API de TMDB en themoviedb.org → Configuración de cuenta → API

Clona, instala y compila:

git clone https://github.com/Laksh-star/mcp-server-tmdb.git
cd mcp-server-tmdb
npm install

Crea un archivo de entorno local y agrega tu clave de TMDB:
```
cp .env.example .env
```
Instala la integración local de Codex y Claude Desktop:
```
npm run install:local
```
Reinicia Codex o Claude Desktop si ya están abiertos.
Verifica con un mensaje como:
```
What movies are trending this week?
```

En Codex, una sesión nueva debería mostrar TMDB en la lista de complementos y exponer el espacio de nombres mcp__tmdb__.

Prueba de superficie de herramientas

Usa esta prueba de humo después de agregar o fusionar herramientas. Verifica el contrato esperado de herramientas MCP y llama a las herramientas principales de flujo de trabajo: compare_movies, find_where_to_watch, get_weekend_watchlist, plan_watch_party, build_franchise_watch_order, build_collection_gap_plan, recommend_from_taste_profile y build_person_watch_path.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/tool-surface-smoke.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

El script escribe un artefacto de verificación compacto en:

examples/tool-surface-smoke.md

Para evitar la acumulación de herramientas, prefiere agregar herramientas de flujo de trabajo que combinen múltiples llamadas de TMDB en una decisión útil para el usuario. Mantén las herramientas de estilo de endpoint sin procesar solo cuando sean primitivas ampliamente reutilizables.

Demostración de tendencias semanales por idioma

Este repositorio incluye una pequeña demostración compartible que llama a la herramienta MCP get_weekly_trending_by_language, que obtiene películas en tendencia semanal en vivo de TMDB y agrupa la primera página actual por original_language de TMDB.

Ejecútala contra el servidor MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-trending

Después de implementar esta versión del Worker, ejecuta la misma demostración contra un endpoint MCP remoto:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Si la implementación es intencionalmente sin autenticación para pruebas personales, omite TMDB_MCP_ACCESS_TOKEN.

Radar semanal de streaming

Este repositorio también incluye un radar semanal basado en scripts. Encadena herramientas MCP existentes en un artefacto Markdown con tendencias de películas, tendencias de TV, impulso de idiomas, selecciones listas para acción, selecciones aptas para familias y una sonda de perfil de gusto.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-radar -- --country US

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-streaming-radar.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US

El script escribe:

examples/weekly-streaming-radar.md

Lista de seguimiento del calendario de estrenos

El calendario de estrenos está disponible como la herramienta MCP build_release_calendar_watchlist. El script de demostración llama a esa herramienta y escribe un artefacto Markdown para el escaneo de ventanas de estreno, candidatos para ver más tarde, selecciones listas para proveedores y líneas base para audiencias amplias.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:release-calendar -- --country US --days 90

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/release-calendar-watchlist.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --days 90

El script escribe:

examples/release-calendar-watchlist.md

Monitor de cambios de proveedores

El monitor de proveedores está basado en scripts porque necesita estado persistente. Llama a find_where_to_watch, compara la lista actual de proveedores contra una instantánea JSON y escribe un informe de diferencias en Markdown que muestra disponibilidad de proveedores nueva, eliminada, sin cambios y faltante.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:provider-monitor -- --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/provider-change-monitor.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

El script escribe:

examples/provider-change-monitor.md
examples/provider-change-snapshot.json

Buscador de brechas de colecciones

El script del buscador de brechas de colecciones ahora llama a la herramienta MCP promovida build_collection_gap_plan y escribe un informe de finalización repetible en Markdown con entradas vistas, entradas faltantes, duración restante, disponibilidad de proveedores y la ruta de finalización más corta.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:collection-gaps -- --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/collection-gap-finder.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

El script escribe:

examples/collection-gap-finder.md

MCP remoto en Cloudflare Workers

Este repositorio también puede ejecutarse como un servidor MCP remoto en Cloudflare Workers. El servidor remoto expone las mismas herramientas de TMDB en /mcp a través de Streamable HTTP, de modo que Claude, Cowork, conectores de Claude Desktop y otros clientes MCP remotos puedan conectarse a una URL pública.

El servidor stdio local existente permanece sin cambios para Codex y uso local de Claude Desktop. El punto de entrada de Cloudflare es src/worker.ts.

El Worker también sirve una demostración de navegador en /: Weekend Watch Concierge. Admite selecciones individuales y modo Watch Party, y luego construye una lista corta clasificada de películas usando descubrimiento de TMDB, tendencias, en cartelera, créditos, pósters y datos de proveedores de visualización. La aplicación de navegador también incluye un cajón de Ayuda para el uso de Cloudflare y un panel de Demostraciones de flujos de trabajo con comandos para artefactos basados en scripts como Weekly Streaming Radar, Provider Change Monitor y Collection Gap Finder.

La demostración de navegador también incluye un panel de superficie de herramientas MCP que llama a la ruta /mcp implementada, verifica el contrato esperado de herramientas y muestra ejemplos de compare_movies, find_where_to_watch, get_weekend_watchlist, plan_watch_party, build_franchise_watch_order, build_collection_gap_plan, recommend_from_taste_profile y build_person_watch_path.

Para la aplicación de navegador completa, el Worker implementado, el token de acceso y la transferencia MCP, consulta docs/weekend-watch-concierge.md.

Implementación

Inicia sesión en Cloudflare:
```
npx wrangler login
```
Almacena tu clave de TMDB como secreto del Worker:
```
npx wrangler secret put TMDB_API_KEY
```
Almacena un token de acceso como secreto del Worker antes de compartir la implementación:
```
npx wrangler secret put ACCESS_TOKEN
```
Cuando ACCESS_TOKEN está configurado, POST /api/concierge y POST /mcp requieren:
```
Authorization: Bearer <your-access-token>
```
Verifica el paquete del Worker:
```
npm run worker:dry-run
```
Implementa:
```
npm run worker:deploy
```

Cloudflare imprimirá una URL como:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev

Usa este endpoint MCP en clientes remotos:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Usa esta URL de demostración de navegador:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/

Conexión desde Claude / Cowork

Para conectores personalizados de Claude:

Abre la configuración de Claude: Customize -> Connectors.
Haz clic en + -> Add custom connector.

Usa la URL MCP del Worker implementado:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Habilita el conector en una conversación y haz una pregunta sobre TMDB, como:
```
What movies are trending this week?
```

Para versiones de Claude Desktop o clientes MCP que aún requieran un comando local, usa el proxy mcp-remote:

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

Nota de seguridad

Si ACCESS_TOKEN no está configurado, el Worker no tiene autenticación para facilitar las pruebas personales. Cualquiera que tenga la URL del Worker puede llamar a las herramientas de TMDB de solo lectura y consumir tu cuota de API de TMDB. Mantén ACCESS_TOKEN configurado o usa Cloudflare Access antes de compartir esto más allá de tus propias cuentas.

Weekend Watch Concierge

Ejecuta la prueba de conserjería sin conexión:

npm test

Esto compila el proyecto TypeScript, inicia un pequeño servidor de accesorios local compatible con TMDB y verifica que createWeekendConcierge clasifique primero una coincidencia de servicio de streaming solicitada mientras respeta el filtro de duración. No necesita una clave de API de TMDB.

Ejecuta el Worker localmente:

npm run worker:dev

Esto sincroniza valores locales de .env en un archivo .dev.vars no rastreado para que Wrangler pueda exponer TMDB_API_KEY al Worker durante el desarrollo local.

Para pruebas locales protegidas, agrega ACCESS_TOKEN a .env. La aplicación de navegador tiene un campo de token de acceso y los scripts de prueba de humo pueden leer ACCESS_TOKEN o TMDB_MCP_ACCESS_TOKEN del entorno de shell.

Abre:

http://127.0.0.1:8787/

Prueba de humo de la API de conserjería después de que el Worker local esté en ejecución:

npm run smoke:concierge

Prueba de humo del endpoint MCP remoto y llama a la herramienta de conserjería orientada a agentes:

node scripts/remote-mcp-smoke.mjs http://127.0.0.1:8787/mcp --call-concierge

Para una implementación protegida:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

O prueba un Worker implementado:

node scripts/concierge-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev

La aplicación usa:

POST /api/concierge para selecciones de películas clasificadas
POST /api/collection-gap-plan para brechas de colecciones de Planning Lab
POST /api/taste-profile para recomendaciones de ajuste de gusto de Planning Lab
POST /api/person-watch-path para rutas de visualización de personas de Planning Lab
GET /health para el estado de la implementación
POST /mcp para clientes MCP remotos

Los agentes pueden llamar a get_weekend_watchlist con:

mood: crowd, thriller, thoughtful, funny, family o mindbend
country: región del proveedor de visualización, por ejemplo IN o US
language: código de idioma original, por ejemplo en, hi, ta, te o any
runtime: minutos máximos, por ejemplo 120, 150 o any
minRating: calificación mínima de TMDB
services: servicios de streaming preferidos
familySafe: configúralo en true para excluir géneros maduros comunes cuando los datos de género de TMDB estén disponibles

Los agentes pueden llamar a plan_watch_party cuando la decisión es para un grupo. Acepta:

moods: de uno a tres valores de crowd, thriller, thoughtful, funny, family o mindbend
groupSize: número de personas que verán
country, language, runtime, minRating y services: mismo significado que la lista de fin de semana
avoidTitles: títulos que el grupo ya ha visto o quiere excluir
familySafe: configúralo en true para excluir géneros maduros comunes cuando los datos de género de TMDB estén disponibles

Los agentes pueden llamar a build_franchise_watch_order para una guía de colección o universo. Acepta:

query: nombre de franquicia o colección, por ejemplo The Matrix, Dune, Batman o Mission Impossible
country: región del proveedor de visualización, por ejemplo IN o US
maxMovies: número máximo de entradas de colección a incluir, de 2 a 20

Los agentes pueden llamar a build_collection_gap_plan para la planificación de finalización de franquicias. Acepta:

query: nombre de la franquicia o colección
watchedTitles: títulos vistos o IDs de películas de TMDB
country: región del proveedor de visualización, por ejemplo IN o US
services: servicios de streaming preferidos
maxMovies: número máximo de entradas de colección a incluir, de 2 a 20

Los agentes pueden llamar a recommend_from_taste_profile para obtener recomendaciones personalizadas. Acepta:

likedTitles: de una a cinco películas que le gustan al usuario
dislikedTitles: películas opcionales que al usuario no le gustan o quiere evitar estilísticamente
country, services, language, runtime y minRating: filtros y preferencias de visualización ahora
maxResults: número de recomendaciones a devolver, de 3 a 10

Los agentes pueden llamar a build_person_watch_path para un actor, director, guionista o miembro del equipo. Acepta:

name: nombre de la persona, por ejemplo Keanu Reeves o Christopher Nolan
country: región del proveedor de visualización, por ejemplo IN o US
services: servicios de streaming preferidos
maxTitles: número de entradas de ruta de visualización a devolver, de 3 a 8

Flujo de trabajo de demostración de Cloudflare MCP

Para un flujo de trabajo de agente de extremo a extremo concreto, ejecuta la demostración de seguimiento de "now playing". Utiliza el servidor MCP como lo haría un cliente remoto:

get_now_playing para el descubrimiento actual en cines en una región seleccionada
get_movie_details para el título seleccionado
get_watch_providers para la disponibilidad de visualización ahora
get_recommendations, con respaldo de get_similar_movies para títulos muy nuevos
get_watch_providers para comprobaciones de disponibilidad de seguimiento

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

MCP alojado en Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/now-playing-follow-on-demo.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --region US

El script escribe el artefacto final aquí:

examples/now-playing-follow-on-demo.md

Qué hace `npm run install:local`

El instalador utiliza el lanzador propiedad del repositorio en plugins/tmdb/scripts/run-server.sh.

Para Codex:

Registra el lanzador como servidor MCP
Instala una carga útil de plugin local de TMDB para que aparezca en la interfaz de plugins

Para Claude Desktop:

Registra el mismo lanzador como servidor MCP local

Actualiza:

~/.codex/config.toml
~/.codex/.tmp/plugins/.agents/plugins/marketplace.json
~/.codex/plugins/cache/openai-curated/tmdb/...
~/Library/Application Support/Claude/claude_desktop_config.json

El lanzador lee TMDB_API_KEY de tu entorno de shell o del archivo .env del repositorio.

Uso con Claude Desktop

Si prefieres la configuración manual, añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

Reinicia Claude Desktop después de editar la configuración.

Uso con Codex

El instalador añade estos bloques a ~/.codex/config.toml:

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

Reinicia Codex después de editar la configuración. En una sesión nueva de Codex, TMDB debería aparecer en la lista de plugins y contribuir con el espacio de nombres mcp__tmdb__.

Validación

Prueba de humo sin conexión:

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

Prueba de humo en línea:

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

Documentación de plugins

Para el empaquetado de plugins, el comportamiento de instalación local y las notas específicas de Codex, consulta plugins/tmdb/README.md.

Uso con BizClaw / NanoClaw

Integrado en el contenedor del agente. Solo tienes que establecer TMDB_API_KEY en tu archivo .env — no se necesita configuración.

Ejemplos de 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?"

Licencia

MIT

TMDB MCP Server

Documentación

Servidor MCP de TMDB

Herramientas

Descubrimiento de películas

Detalles de películas

Series de TV

Personas

Recursos

Inicio rápido

Prueba de superficie de herramientas

Demostración de tendencias semanales por idioma

Radar semanal de streaming

Lista de seguimiento del calendario de estrenos

Monitor de cambios de proveedores

Buscador de brechas de colecciones

MCP remoto en Cloudflare Workers

Implementación

Conexión desde Claude / Cowork

Nota de seguridad

Weekend Watch Concierge

Flujo de trabajo de demostración de Cloudflare MCP

Qué hace npm run install:local

Uso con Claude Desktop

Uso con Codex

Validación

Documentación de plugins

Uso con BizClaw / NanoClaw

Ejemplos de prompts

Licencia

Qué hace `npm run install:local`