IMDb MCP Server

Proporciona información de películas y programas de televisión utilizando el servicio de la API de IMDb.

Documentación

Servidor MCP de IMDb

Un servidor Python que implementa el Protocolo de Contexto de Modelo (MCP) para información de películas y programas de televisión utilizando el servicio de API de IMDb.

Descripción General

Este servidor proporciona un conjunto completo de herramientas para acceder a datos de IMDb a través de la API de IMDb. Actúa como un puente entre agentes y la base de datos de IMDb, ofreciendo información detallada sobre películas, programas de televisión, actores, directores y más.

Características

🎬 Capacidades de búsqueda de películas y programas de TV
📋 Información detallada sobre películas y programas de TV
👨‍👩‍👧‍👦 Información de reparto y equipo
🏆 Listas de contenido mejor calificado y popular
💰 Datos de taquilla
🌍 Información de películas específica por país (con enfoque especial en el cine indio)
🔜 Próximos estrenos
🔄 Sistema eficiente de caché de respuestas

Requisitos

Python: 3.13 o superior
Gestor de Paquetes: uv (recomendado) o pip
Cuenta de RapidAPI: Requerida para el acceso a la API de IMDb

Configuración

Este servidor requiere tu propia clave de API de RapidAPI para el servicio de API de IMDb:

Crea una cuenta en RapidAPI
Suscríbete a la API de IMDb en RapidAPI (hay un plan gratuito disponible)
Copia tu clave de API desde el panel de RapidAPI
Proporciónala a través de la variable de entorno RAPID_API_KEY_IMDB, usando la que se ajuste a tu configuración:
- Configuración del cliente MCP — establécelo en el bloque env (ver Instalación). Esta es la forma habitual.
- Shell: export RAPID_API_KEY_IMDB=your_api_key_here
- Archivo .env: copia .env.example a .env, luego ejecuta con uv run --env-file .env imdb-server
- HTTP / Docker: pasa -e RAPID_API_KEY_IMDB=... al contenedor

La clave solo se necesita cuando se llama realmente a una herramienta — el servidor se inicia y lista sus herramientas sin ella.

Herramientas

Herramientas de Búsqueda

Herramienta	Descripción	Ejemplo
search_imdb	Busca películas y programas de TV con varias opciones de filtrado	`search_imdb(primary_title="Inception")`

Herramientas de ID de IMDb

Herramienta	Descripción	Ejemplo
get_imdb_details	Recupera información detallada sobre una película o programa de TV	`get_imdb_details(imdb_id="tt1375666")`
get_directors	Recupera los directores de una película	`get_directors(imdb_id="tt1375666")`
get_cast	Recupera el reparto de una película	`get_cast(imdb_id="tt1375666")`
get_writers	Recupera los guionistas de una película	`get_writers(imdb_id="tt1375666")`

Herramientas de Configuración

Herramienta	Descripción	Ejemplo
get_types	Obtiene todos los tipos de contenido disponibles	`get_types()`
get_genres	Obtiene todos los géneros disponibles	`get_genres()`
get_countries	Obtiene todos los países disponibles	`get_countries()`
get_languages	Obtiene todos los idiomas disponibles	`get_languages()`

Herramientas de Películas

Paginadas (5 resultados por página)

Herramienta	Descripción	Ejemplo
get_top_250_movies	Obtiene las 250 mejores películas de IMDb	`get_top_250_movies(start=0)`
get_top_box_office_us	Obtiene los registros de taquilla de EE. UU.	`get_top_box_office_us(start=0)`
get_most_popular_movies	Obtiene las películas más populares	`get_most_popular_movies(start=0)`

Herramientas de Programas de TV

Paginadas (5 resultados por página)

Herramienta	Descripción	Ejemplo
get_top_250_tv_shows	Obtiene los 250 mejores programas de TV de IMDb	`get_top_250_tv_shows(start=0)`
get_most_popular_tv_shows	Obtiene los programas de TV más populares	`get_most_popular_tv_shows(start=0)`

Herramientas de Próximos Estrenos

Paginadas (5 resultados por página)

Herramienta	Descripción	Ejemplo
get_upcoming_releases	Obtiene los próximos estrenos de películas y programas de TV por país	`get_upcoming_releases(country_code="US", type="MOVIE", start=0)`
get_country_codes_for_upcoming_releases	Obtiene los códigos de país disponibles para próximos estrenos	`get_country_codes_for_upcoming_releases()`

Herramientas de Destacados de India

Paginadas (5 resultados por página)

Herramienta	Descripción	Ejemplo
get_top_rated_malayalam_movies	Obtiene las 50 mejores películas en malayalam	`get_top_rated_malayalam_movies(start=0)`
get_upcoming_indian_movies	Obtiene las películas indias más anticipadas	`get_upcoming_indian_movies(start=0)`
get_trending_tamil_movies	Obtiene las películas tamil en tendencia	`get_trending_tamil_movies(start=0)`
get_trending_telugu_movies	Obtiene las películas telugu en tendencia	`get_trending_telugu_movies(start=0)`
get_top_rated_tamil_movies	Obtiene las 50 mejores películas tamil	`get_top_rated_tamil_movies(start=0)`
get_top_rated_telugu_movies	Obtiene las 50 mejores películas telugu	`get_top_rated_telugu_movies(start=0)`
get_top_rated_indian_movies	Obtiene las 250 mejores películas indias	`get_top_rated_indian_movies(start=0)`

Ejemplo de Prompt y Respuesta

¿Cuáles son las 5 películas de acción que se estrenarán en el futuro más cercano?

Encontraré las próximas películas de acción para ti.

Se llamó a la herramienta MCP get_upcoming_releases

Ahora buscaré las películas de acción entre estos próximos estrenos:

Se llamó a la herramienta MCP get_upcoming_releases

Según los resultados de búsqueda, aquí están las 5 próximas películas de acción que se estrenarán en el futuro más cercano:

A Minecraft Movie (4 de abril de 2025)
- Géneros: Acción, Aventura, Comedia
- Descripción: Cuatro inadaptados son arrastrados a través de un portal hacia un mundo cúbico y se embarcan en una búsqueda con un artesano experto para volver a casa.
Freaky Tales (4 de abril de 2025)
- Géneros: Acción, Aventura, Comedia
- Descripción: Cuatro historias interconectadas ambientadas en 1987 en Oakland, CA, sobre el amor por la música, las películas, las personas, los lugares y los recuerdos.
Wake Up (4 de abril de 2025)
- Géneros: Acción, Terror
- Descripción: Jóvenes activistas invaden una tienda de muebles para protestar por problemas ambientales, pero se encuentran atrapados con un guardia nocturno obsesionado con la caza.
Warfare (11 de abril de 2025)
- Géneros: Acción, Drama, Guerra
- Descripción: Basada en las experiencias reales del ex Navy Seal Ray Mendoza durante la Guerra de Irak.
The Amateur (11 de abril de 2025)
- Géneros: Acción, Suspenso
- Descripción: Un criptógrafo de la CIA chantajea a su agencia para que lo entrene y persiga a los terroristas que mataron a su esposa.

Instalación

Este es un servidor MCP autónomo que ejecutas localmente con tu propia clave de RapidAPI. Smithery ya no ofrece alojamiento administrado gratuito, por lo que no hay una instancia remota compartida — clona (o uvx) el servidor y apunta tu cliente MCP hacia él.

Opción 1: Ejecutar con uvx (sin clonar)

Si tienes uv instalado, agrega esto a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "imdb_server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uzaysozen/imdb-mcp-server",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

Opción 2: Clonar y ejecutar con uv

Instala uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Clona este repositorio e instala las dependencias:

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server
uv sync

Agrega esto a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "imdb_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/imdb-mcp-server",
        "run",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

Opción 3: Autoalojamiento sobre HTTP (Docker)

Para un servidor remoto compartido y siempre activo, ejecútalo en modo HTTP detrás de tu propio endpoint HTTPS. Esto es opcional y solo es necesario si varios clientes deben acceder a una sola instancia.

Clona este repositorio

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

Construye y ejecuta la imagen de Docker

docker build -t imdb_server .
docker run -d -p 8081:8081 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

El contenedor se ejecuta en modo HTTP en el puerto 8081, sirviendo el endpoint de MCP en /mcp. Colócalo detrás de un proxy inverso / plataforma que termine TLS. Si deseas que aparezca en Smithery, registra tu URL pública https://.../mcp como servidor externo en smithery.ai/new.

Iniciando el Servidor

Modo Stdio (Predeterminado para desarrollo local)

# Using uv (recommended)
uv run imdb-server

# Or directly with Python module
python -m imdb_mcp_server

Modo HTTP (para autoalojamiento)

# Using uv
TRANSPORT=http uv run imdb-server

# Or with Python module
TRANSPORT=http python -m imdb_mcp_server

# With custom port
TRANSPORT=http PORT=8081 uv run imdb-server

Después de agregar tu configuración elegida, reinicia tu cliente MCP (por ejemplo, Claude Desktop) para cargar el servidor de IMDb. Podrás usar todas las herramientas de datos de películas y programas de TV en tus conversaciones.

Detalles Técnicos

El servidor está construido sobre:

Python 3.13+: Entorno de ejecución de Python moderno
MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer): transportes stdio y HTTP Streamable
API de IMDb vía RapidAPI: Fuente de datos principal
Requests: Biblioteca de comunicación con la API
uv: Gestor y ejecutor de paquetes de Python rápido
Sistema de caché en memoria personalizado: Caché de respuestas optimizado con evicción LRU
Paginación inteligente: Limita los resultados a 5 elementos por solicitud, optimizando para el consumo de agentes de IA

Modos de Transporte

El servidor admite dos modos de transporte, seleccionados por la variable de entorno TRANSPORT:

Modo Stdio (TRANSPORT sin configurar — el predeterminado): comunicación MCP a través de entrada/salida estándar
- Se usa para clientes MCP locales (Claude Desktop, Claude Code, Cursor, etc.)
- La clave de API proviene de la variable de entorno RAPID_API_KEY_IMDB
Modo HTTP (TRANSPORT=http): transporte HTTP Streamable
- Para autoalojar una instancia compartida (Docker, o cualquier plataforma que ejecute el contenedor)
- Sirve el endpoint de MCP en /mcp
- De un solo inquilino: la clave de API proviene de RAPID_API_KEY_IMDB en el servidor
- Se vincula a 0.0.0.0:8081 de forma predeterminada (variables de entorno HOST / PORT); ejecútalo detrás de un proxy que termine TLS

Sistema de Paginación

Todas las herramientas de recuperación de datos implementan paginación para mejorar el rendimiento de los agentes de IA:

Propósito

Respuestas Optimizadas para IA: Limita cada respuesta a 5 elementos, evitando abrumar a los agentes de IA que procesan los datos
Resultados Enfocados: Ayuda a los agentes a proporcionar información más relevante y concisa a los usuarios
Procesamiento Mejorado: Reduce la carga cognitiva en los agentes de IA al analizar datos de películas y programas de TV

Implementación

Cada endpoint paginado acepta un parámetro start (predeterminado: 0)
Los resultados incluyen metadatos de navegación (totalCount, hasMore, nextStart)
Tamaño de página consistente de 5 elementos en todos los endpoints de colección
Ejemplo de solicitud con paginación: get_top_250_movies(start=5) devuelve los elementos 6-10

Beneficios

Mejores Respuestas del Agente: Evita que los agentes de IA reciban demasiados datos a la vez
Información Manejable: Crea fragmentos de datos digeribles que los agentes pueden procesar de manera efectiva
Acceso Secuencial: Permite la exploración estructurada de grandes conjuntos de datos a través de múltiples llamadas a herramientas

Sistema de Caché

El servidor implementa un sistema de caché eficiente para mejorar el rendimiento y reducir las llamadas a la API:

Características

Caché en Memoria: Almacena respuestas de la API en memoria para una recuperación rápida
Expiración y Tamaño Configurables: Las entradas de caché expiran después de un período de tiempo personalizable (predeterminado: 10 minutos) y tienen un tamaño predeterminado de 100 claves de caché
Limpieza Automática de Caché: Periódicamente (predeterminado: 5 minutos) elimina entradas expiradas para gestionar el uso de memoria mediante un hilo en segundo plano
Claves de Caché: Se generan según la URL y los parámetros de consulta para garantizar la unicidad

Beneficios

Uso Reducido de la API: Ayuda a mantenerse dentro de los límites de velocidad de la API reutilizando respuestas
Tiempos de Respuesta Más Rápidos: Elimina la latencia de red para consultas en caché
Eficiencia de Costos: Minimiza el número de llamadas a la API, especialmente para consultas populares o repetidas

Configuración

El tamaño de la caché y el tiempo de expiración se pueden ajustar en src/imdb_mcp_server/cache.py:

# Defaults: 600 seconds (10 minutes) and 100 cache keys
# You can customize by modifying the ResponseCache instantiation:
response_cache = ResponseCache(max_size=100, expiry_seconds=600)

# Example with custom values:
# response_cache = ResponseCache(max_size=50, expiry_seconds=120)

Limitaciones

Se aplican límites de tasa de API según tu suscripción de RapidAPI
Alguna información detallada puede requerir llamadas API adicionales
Los resultados de búsqueda pueden estar limitados a un cierto número de elementos por solicitud
La caché en memoria se pierde cuando el servidor se reinicia
Todas las respuestas paginadas devuelven un máximo de 5 elementos por página

Solución de problemas

Problema	Solución
Clave API no reconocida	Asegúrate de que `RAPID_API_KEY_IMDB` esté configurada — en el bloque `env` de la configuración de tu cliente MCP, tu shell, `.env`, o `-e` en el contenedor Docker
`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`	Estás en una versión antigua con `mcp` 2.x instalado. Obtén la última versión (este servidor apunta a `mcp` 2.x / `MCPServer`) y ejecuta `uv sync`
`HTTP 401` / `HTTP 403` de la API de IMDb	Tu clave de RapidAPI no es válida o no está suscrita a la API de IMDb. (Re) suscríbete a la API de IMDb en RapidAPI y copia la nueva clave
`HTTP 404` de la API de IMDb	La suscripción de RapidAPI está inactiva o el endpoint upstream cambió. Verifica el estado de la suscripción en tu panel de RapidAPI
El antiguo comando `npx @smithery/cli install` falla	Smithery terminó el hosting administrado gratuito (marzo de 2026), por lo que no hay una instancia remota compartida. Instala localmente en su lugar — consulta Instalación
Límite de tasa excedido	Verifica tu nivel y límites de suscripción de RapidAPI en Panel de RapidAPI
Errores de tiempo de espera	El servidor tiene un tiempo de espera de 30 segundos; para solicitudes grandes, intenta limitar los parámetros o usar paginación
Resultados vacíos	Intenta términos de búsqueda más amplios o verifica si el contenido existe en la base de datos de IMDb
Alto uso de memoria	Si se ejecuta durante períodos prolongados con muchas consultas únicas, reinicia el servidor ocasionalmente para limpiar la caché
Puerto ya en uso	Cambia el puerto usando la variable de entorno `PORT` (solo modo HTTP): `TRANSPORT=http PORT=8082 uv run imdb-server`
Errores de importación	Asegúrate de que todas las dependencias estén instaladas: `uv sync` (o `pip install "mcp[cli]>=2.1,<3" requests`)
Conexión rechazada (Docker)	Asegúrate de que el contenedor esté ejecutándose: `docker ps` y revisa los registros: `docker logs imdb_server`

Licencia

Este servidor MCP está disponible bajo la Licencia MIT.