Servidor MCP de TMDB

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

Herramientas

Descubrimiento de películas

• get_weekend_watchlist — Lista corta de fin de semana clasificada por estado de ánimo, país, idioma, duración, calificación y servicios

• search_movies — Búsqueda por título/palabras clave → títulos, IDs, calificaciones, resúmenes

• get_trending — Las 10 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, filtro de año opcional

• advanced_search — Filtrar por género, año, calificación mínima, orden, idioma

• search_by_keyword — Encontrar películas por tema/palabra clave (ej. "zombie", "heist")

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 de 2 a 5 IDs de películas con calificaciones, duración, reparto, director, proveedores y notas de ajuste

• get_recommendations — Las 5 mejores 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 de 1 a 5 títulos de películas y devolver la disponibilidad de streaming/alquiler/compra con coincidencias de servicios preferidos

Programas de TV

• search_tv_shows — Buscar series de TV por título

• get_trending_tv — Los 10 programas de TV en tendencia (timeWindow: "day" | "week")

Personas

• search_person — Encontrar actores, directores, equipo por nombre → ID + trabajos conocidos

• get_person_details — Biografía completa + filmografía (películas + TV) por personId

Recursos

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

Related MCP server: Usher MCP

Inicio rápido

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

2. Clona, instala y compila:

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

3. Crea un archivo env local y añade tu clave de TMDB:

   cp .env.example .env

4. Instala la integración local de Codex y Claude Desktop:

   npm run install:local

5. Reinicia Codex o Claude Desktop si ya están abiertos.

6. Verifica con un prompt como:

   What movies are trending this week?

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

Prueba de humo de la superficie de herramientas

Usa esta prueba de humo después de añadir o fusionar herramientas. Verifica el contrato de herramientas MCP esperado y llama a las herramientas de flujo de trabajo principales: compare_movies, find_where_to_watch y get_weekend_watchlist.

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 sobrecarga de herramientas, prefiere añadir herramientas de flujo de trabajo que combinen múltiples llamadas a TMDB en una decisión útil para el usuario. Mantén las herramientas de estilo endpoint sin procesar solo cuando sean primitivas ampliamente reutilizables.

Demo de idioma en tendencia semanal

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

Ejecútalo contra el servidor MCP stdio local:

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

Después de desplegar esta versión del Worker, ejecuta la misma demo 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 el despliegue es intencionalmente sin autenticación para pruebas personales, omite TMDB_MCP_ACCESS_TOKEN.

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 sobre HTTP transmitible, por lo que Claude, Cowork, conectores de Claude Desktop y otros clientes MCP remotos pueden conectarse a una URL pública.

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

El Worker también sirve una demo de navegador en /: Weekend Watch Concierge. Solicita estado de ánimo, país, idioma, duración, calificación y servicios de streaming, luego construye una lista corta de películas clasificadas usando el descubrimiento de TMDB, tendencias, estrenos, créditos, pósteres y datos de proveedores de visualización.

La demo del navegador también incluye un panel de superficie de herramientas MCP que llama a la ruta /mcp desplegada, verifica el contrato de herramientas esperado y muestrea compare_movies, find_where_to_watch y get_weekend_watchlist.

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

Despliegue

1. Inicia sesión en Cloudflare:

   npx wrangler login

2. Almacena tu clave de TMDB como un secreto de Worker:

   npx wrangler secret put TMDB_API_KEY

3. Almacena un token de acceso como un secreto de Worker antes de compartir el despliegue:

   npx wrangler secret put ACCESS_TOKEN

   Cuando se establece ACCESS_TOKEN, POST /api/concierge y POST /mcp requieren:

   Authorization: Bearer <your-access-token>

4. Verifica el paquete del Worker:

   npm run worker:dry-run

5. Despliega:

   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 demo del navegador:

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

Conectar desde Claude / Cowork

Para conectores personalizados de Claude:

1. Abre la configuración de Claude: Customize -> Connectors.

2. Haz clic en + -> Add custom connector.

3. Usa la URL del Worker MCP desplegado:

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

4. 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 requieren 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 solo lectura de TMDB y consumir tu cuota de API de TMDB. Mantén ACCESS_TOKEN configurado o usa Cloudflare Access antes de compartir esto fuera de tus propias cuentas.

Weekend Watch Concierge

Ejecuta la prueba de concierge offline:

npm test

Esto construye el proyecto TypeScript, inicia un pequeño servidor de fixtures compatible con TMDB local 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 los 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, añade ACCESS_TOKEN a .env. La aplicación del navegador tiene un campo de token de acceso y los scripts de prueba pueden leer ACCESS_TOKEN o TMDB_MCP_ACCESS_TOKEN desde el entorno del shell.

Abre:

http://127.0.0.1:8787/

Prueba de humo de la API de concierge 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 concierge orientada al agente:

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

Para un despliegue protegido:

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

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

La aplicación utiliza:

• POST /api/concierge para selecciones de películas clasificadas

• GET /health para la salud del despliegue

• 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

Flujo de trabajo de demo de Cloudflare MCP

Para un flujo de trabajo de agente concreto de extremo a extremo, ejecuta la demo de seguimiento de estrenos. Utiliza el servidor MCP como lo haría un cliente remoto:

1. get_now_playing para el descubrimiento actual en cines en una región seleccionada

2. get_movie_details para el título seleccionado

3. get_watch_providers para la disponibilidad de visualización inmediata

4. get_recommendations, con respaldo de get_similar_movies para títulos muy nuevos

5. 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 un servidor MCP

• Instala una carga útil de plugin TMDB local para que aparezca en la interfaz de usuario del plugin

Para Claude Desktop:

• Registra el mismo lanzador como un 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 desde tu entorno de shell o desde el 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 offline:

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

Prueba de humo online:

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

Documentación del plugin

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

Uso con BizClaw / NanoClaw

Integrado en el contenedor del agente. Solo establece 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