IMDb MCP Server

Fornece informações sobre filmes e programas de TV usando o serviço da API do IMDb.

Documentação

IMDb MCP Server

Um servidor Python que implementa o Model Context Protocol (MCP) para informações de filmes e programas de TV usando o serviço de API do IMDb.

Sumário

Visão Geral
Recursos
Requisitos
Configuração
Ferramentas
Exemplo de Prompt e Resposta
Instalação
Iniciando o Servidor
Detalhes Técnicos
Limitações
Solução de Problemas
Licença

Visão Geral

Este servidor fornece um conjunto abrangente de ferramentas para acessar dados do IMDb através da API do IMDb. Ele atua como uma ponte entre agentes e o banco de dados do IMDb, oferecendo informações detalhadas sobre filmes, programas de TV, atores, diretores e muito mais.

Recursos

🎬 Capacidades de busca de filmes e programas de TV
📋 Informações detalhadas sobre filmes e programas de TV
👨‍👩‍👧‍👦 Informações de elenco e equipe técnica
🏆 Listas de conteúdo mais bem avaliado e popular
💰 Dados de bilheteria
🌍 Informações de filmes específicas por país (com foco especial no cinema indiano)
🔜 Lançamentos futuros
🔄 Sistema eficiente de cache de respostas

Requisitos

Python: 3.13 ou superior
Gerenciador de Pacotes: uv (recomendado) ou pip
Conta RapidAPI: Necessária para acesso à API do IMDb

Configuração

Este servidor requer sua própria chave de API do RapidAPI para o serviço de API do IMDb:

Crie uma conta no RapidAPI
Assine a API do IMDb no RapidAPI (um plano gratuito está disponível)
Copie sua chave de API do painel do RapidAPI
Forneça-a através da variável de ambiente RAPID_API_KEY_IMDB, usando o que melhor se adequar à sua configuração:
- Config do cliente MCP — defina-a no bloco env (veja Instalação). Esta é a forma usual.
- Shell: export RAPID_API_KEY_IMDB=your_api_key_here
- Arquivo .env: copie .env.example para .env, depois execute com uv run --env-file .env imdb-server
- HTTP / Docker: passe -e RAPID_API_KEY_IMDB=... para o contêiner

A chave só é necessária quando uma ferramenta é realmente chamada — o servidor inicia e lista suas ferramentas sem ela.

Ferramentas

Ferramentas de Busca

Ferramenta	Descrição	Exemplo
search_imdb	Busca filmes e programas de TV com várias opções de filtro	`search_imdb(primary_title="Inception")`

Ferramentas de ID IMDb

Ferramenta	Descrição	Exemplo
get_imdb_details	Recupera informações detalhadas sobre um filme ou programa de TV	`get_imdb_details(imdb_id="tt1375666")`
get_directors	Recupera os diretores de um filme	`get_directors(imdb_id="tt1375666")`
get_cast	Recupera o elenco de um filme	`get_cast(imdb_id="tt1375666")`
get_writers	Recupera os roteiristas de um filme	`get_writers(imdb_id="tt1375666")`

Ferramentas de Configuração

Ferramenta	Descrição	Exemplo
get_types	Obtém todos os tipos de conteúdo disponíveis	`get_types()`
get_genres	Obtém todos os gêneros disponíveis	`get_genres()`
get_countries	Obtém todos os países disponíveis	`get_countries()`
get_languages	Obtém todos os idiomas disponíveis	`get_languages()`

Ferramentas de Filmes

Paginadas (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_top_250_movies	Obtém os 250 melhores filmes do IMDb	`get_top_250_movies(start=0)`
get_top_box_office_us	Obtém os registros de bilheteria dos EUA	`get_top_box_office_us(start=0)`
get_most_popular_movies	Obtém os filmes mais populares	`get_most_popular_movies(start=0)`

Ferramentas de Programas de TV

Paginadas (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_top_250_tv_shows	Obtém os 250 melhores programas de TV do IMDb	`get_top_250_tv_shows(start=0)`
get_most_popular_tv_shows	Obtém os programas de TV mais populares	`get_most_popular_tv_shows(start=0)`

Ferramentas de Lançamentos Futuros

Paginadas (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_upcoming_releases	Obtém lançamentos futuros de filmes e programas de TV por país	`get_upcoming_releases(country_code="US", type="MOVIE", start=0)`
get_country_codes_for_upcoming_releases	Obtém códigos de país disponíveis para lançamentos futuros	`get_country_codes_for_upcoming_releases()`

Ferramentas de Destaque da Índia

Paginadas (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_top_rated_malayalam_movies	Obtém os 50 melhores filmes em malaiala	`get_top_rated_malayalam_movies(start=0)`
get_upcoming_indian_movies	Obtém os filmes indianos futuros mais aguardados	`get_upcoming_indian_movies(start=0)`
get_trending_tamil_movies	Obtém filmes tâmeis em alta	`get_trending_tamil_movies(start=0)`
get_trending_telugu_movies	Obtém filmes em telugu em alta	`get_trending_telugu_movies(start=0)`
get_top_rated_tamil_movies	Obtém os 50 melhores filmes tâmeis	`get_top_rated_tamil_movies(start=0)`
get_top_rated_telugu_movies	Obtém os 50 melhores filmes em telugu	`get_top_rated_telugu_movies(start=0)`
get_top_rated_indian_movies	Obtém os 250 melhores filmes indianos	`get_top_rated_indian_movies(start=0)`

Exemplo de Prompt e Resposta

Quais são os 5 filmes de ação que serão lançados em um futuro próximo?

Vou encontrar os próximos filmes de ação para você.

Ferramenta MCP chamada get_upcoming_releases

Agora vou procurar os filmes de ação entre esses lançamentos futuros:

Ferramenta MCP chamada get_upcoming_releases

Com base nos resultados da busca, aqui estão os 5 próximos filmes de ação que serão lançados em um futuro próximo:

A Minecraft Movie (4 de abril de 2025)
- Gêneros: Ação, Aventura, Comédia
- Descrição: Quatro desajustados são puxados por um portal para um mundo cúbico de maravilhas e embarcam em uma missão com um artesão especialista para voltar para casa.
Freaky Tales (4 de abril de 2025)
- Gêneros: Ação, Aventura, Comédia
- Descrição: Quatro histórias interconectadas ambientadas em Oakland, CA, em 1987, sobre o amor pela música, filmes, pessoas, lugares e memórias.
Wake Up (4 de abril de 2025)
- Gêneros: Ação, Terror
- Descrição: Jovens ativistas invadem uma loja de móveis para protestar contra questões ambientais, mas se veem presos com um guarda noturno obcecado por caça.
Warfare (11 de abril de 2025)
- Gêneros: Ação, Drama, Guerra
- Descrição: Baseado nas experiências reais do ex-Navy Seal Ray Mendoza durante a Guerra do Iraque.
The Amateur (11 de abril de 2025)
- Gêneros: Ação, Suspense
- Descrição: Um criptógrafo da CIA chantageia sua agência para treiná-lo a perseguir terroristas que mataram sua esposa.

Instalação

Este é um servidor MCP autônomo que você executa localmente com sua própria chave RapidAPI. O Smithery não oferece mais hospedagem gerenciada gratuita, portanto não há instância remota compartilhada — clone (ou uvx) o servidor e aponte seu cliente MCP para ele.

Opção 1: Executar com uvx (sem necessidade de clonar)

Se você tiver o uv instalado, adicione isto à configuração do seu cliente MCP (ex.: 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"
      }
    }
  }
}

Opção 2: Clonar e executar com uv

Instale o uv:

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

Clone este repositório e instale as dependências:

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

Adicione isto à configuração do seu 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"
      }
    }
  }
}

Opção 3: Auto-hospedagem via HTTP (Docker)

Para um servidor remoto compartilhado e sempre ativo, execute-o em modo HTTP atrás do seu próprio endpoint HTTPS. Isso é opcional e só é necessário se vários clientes devem acessar uma única instância.

Clone este repositório

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

Construa e execute a imagem 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

O contêiner executa em modo HTTP na porta 8081, servindo o endpoint MCP em /mcp. Coloque-o atrás de um proxy reverso / plataforma que encerre TLS. Se você quiser listá-lo no Smithery, registre sua URL pública https://.../mcp como um servidor externo em smithery.ai/new.

Iniciando o Servidor

Modo Stdio (Padrão para desenvolvimento local)

# Using uv (recommended)
uv run imdb-server

# Or directly with Python module
python -m imdb_mcp_server

Modo HTTP (para auto-hospedagem)

# 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

Após adicionar sua configuração escolhida, reinicie seu cliente MCP (ex.: Claude Desktop) para carregar o servidor IMDb. Você poderá então usar todas as ferramentas de dados de filmes e programas de TV em suas conversas.

Detalhes Técnicos

O servidor é construído com:

Python 3.13+: Runtime Python moderno
MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer): transportes stdio e HTTP Streamable
API do IMDb via RapidAPI: Fonte primária de dados
Requests: Biblioteca de comunicação com API
uv: Gerenciador e executor rápido de pacotes Python
Sistema de cache em memória personalizado: Cache de respostas otimizado com evicção LRU
Paginação inteligente: Limita os resultados a 5 itens por solicitação, otimizando para consumo por agentes de IA

Modos de Transporte

O servidor suporta dois modos de transporte, selecionados pela variável de ambiente TRANSPORT:

Modo Stdio (TRANSPORT não definido — o padrão): comunicação MCP via entrada/saída padrão
- Usado para clientes MCP locais (Claude Desktop, Claude Code, Cursor, etc.)
- A chave de API vem da variável de ambiente RAPID_API_KEY_IMDB
Modo HTTP (TRANSPORT=http): transporte HTTP Streamable
- Para auto-hospedar uma instância compartilhada (Docker, ou qualquer plataforma que execute o contêiner)
- Serve o endpoint MCP em /mcp
- Single-tenant: a chave de API vem de RAPID_API_KEY_IMDB no servidor
- Vincula 0.0.0.0:8081 por padrão (variáveis de ambiente HOST / PORT); execute-o atrás de um proxy que encerre TLS

Sistema de Paginação

Todas as ferramentas de recuperação de dados implementam paginação para melhorar o desempenho dos agentes de IA:

Propósito

Respostas Otimizadas para IA: Limita cada resposta a 5 itens, evitando sobrecarga em agentes de IA que processam os dados
Resultados Focados: Ajuda os agentes a fornecer informações mais relevantes e concisas aos usuários
Processamento Melhorado: Reduz a carga cognitiva nos agentes de IA ao analisar dados de filmes e programas de TV

Implementação

Cada endpoint paginado aceita um parâmetro start (padrão: 0)
Os resultados incluem metadados de navegação (totalCount, hasMore, nextStart)
Tamanho de página consistente de 5 itens em todos os endpoints de coleção
Exemplo de solicitação com paginação: get_top_250_movies(start=5) retorna os itens 6-10

Benefícios

Melhores Respostas do Agente: Evita que agentes de IA recebam muitos dados de uma vez
Informações Gerenciáveis: Cria blocos de dados digeríveis que os agentes podem processar de forma eficaz
Acesso Sequencial: Permite exploração estruturada de grandes conjuntos de dados através de múltiplas chamadas de ferramentas

Sistema de Cache

O servidor implementa um sistema de cache eficiente para melhorar o desempenho e reduzir chamadas de API:

Recursos

Cache em Memória: Armazena respostas de API em memória para recuperação rápida
Expiração e Tamanho Configuráveis: As entradas de cache expiram após um período personalizável (padrão: 10 minutos) e têm um tamanho padrão de 100 chaves de cache
Limpeza Automática de Cache: Remove periodicamente (padrão: 5 minutos) entradas expiradas para gerenciar o uso de memória usando um thread em segundo plano
Chaves de Cache: Geradas com base na URL e nos parâmetros de consulta para garantir exclusividade

Benefícios

Uso Reduzido de API: Ajuda a permanecer dentro dos limites de taxa da API reutilizando respostas
Tempos de Resposta Mais Rápidos: Elimina latência de rede para consultas em cache
Eficiência de Custo: Minimiza o número de chamadas de API, especialmente para consultas populares ou repetidas

Configuração

O tamanho do cache e o tempo de expiração podem ser ajustados em 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)

Limitações

Limites de taxa da API se aplicam de acordo com sua assinatura do RapidAPI
Algumas informações detalhadas podem exigir chamadas adicionais à API
Os resultados da pesquisa podem ser limitados a um certo número de itens por solicitação
O cache em memória é perdido quando o servidor reinicia
Todas as respostas paginadas retornam no máximo 5 itens por página

Solução de Problemas

Problema	Solução
Chave da API não reconhecida	Certifique-se de que `RAPID_API_KEY_IMDB` esteja definida — no bloco `env` da configuração do seu cliente MCP, no seu shell, `.env` ou `-e` no contêiner Docker
`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`	Você está em um checkout antigo com `mcp` 2.x instalado. Puxe o mais recente (este servidor tem como alvo `mcp` 2.x / `MCPServer`) e execute `uv sync`
`HTTP 401` / `HTTP 403` da API IMDb	Sua chave RapidAPI é inválida ou não está inscrita na API IMDb. (Re)inscreva-se na API IMDb no RapidAPI e copie a nova chave
`HTTP 404` da API IMDb	A assinatura do RapidAPI está inativa ou o endpoint upstream mudou. Verifique o status da assinatura no seu painel do RapidAPI
O antigo comando `npx @smithery/cli install` falha	A Smithery encerrou a hospedagem gerenciada gratuita (março de 2026), então não há instância remota compartilhada. Instale localmente — veja Instalação
Limite de taxa excedido	Verifique o nível e os limites da sua assinatura RapidAPI no Painel do RapidAPI
Erros de tempo limite	O servidor tem um tempo limite de 30 segundos; para solicitações grandes, tente limitar os parâmetros ou usar paginação
Resultados vazios	Tente termos de busca mais amplos ou verifique se o conteúdo existe no banco de dados do IMDb
Alto uso de memória	Se estiver executando por períodos prolongados com muitas consultas exclusivas, reinicie o servidor ocasionalmente para limpar o cache
Porta já em uso	Altere a porta usando a variável de ambiente `PORT` (somente modo HTTP): `TRANSPORT=http PORT=8082 uv run imdb-server`
Erros de importação	Certifique-se de que todas as dependências estejam instaladas: `uv sync` (ou `pip install "mcp[cli]>=2.1,<3" requests`)
Conexão recusada (Docker)	Certifique-se de que o contêiner esteja em execução: `docker ps` e verifique os logs: `docker logs imdb_server`

Licença

Este servidor MCP está disponível sob a Licença MIT.