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 clasificada para el fin de semana según 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")

• 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)

• 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)

Programas de TV

• search_tv_shows — Búsqueda de 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: TMDB MCP Server

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__.

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 HTTP transmitible, por lo que Claude, Cowork, los 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 demostración en el 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 utilizando datos de descubrimiento, tendencias, estrenos, créditos, pósteres y proveedores de visualización de TMDB.

Para la aplicación de navegador completa, el Worker desplegado, el token de acceso y la transferencia 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 demostración 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 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/

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

npm run smoke:concierge

Realiza una prueba de humo del endpoint MCP remoto y llama a la herramienta de conserjería 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 el estado 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

Qué hace npm run install:local

El instalador utiliza el lanzador propio 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 de plugins

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