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 séries de TV usando o serviço da API 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 IMDb. Ele serve como uma ponte entre agentes e o banco de dados do IMDb, oferecendo informações detalhadas sobre filmes, séries de TV, atores, diretores e muito mais.

Recursos

🎬 Capacidades de busca de filmes e séries de TV
📋 Informações detalhadas sobre filmes e séries de TV
👨‍👩‍👧‍👦 Informações sobre elenco e equipe
🏆 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 IMDb

Configuração

Este servidor requer uma chave de API da RapidAPI para o serviço da API IMDb:

Crie uma conta no RapidAPI
Assine a IMDb API no RapidAPI
Configure a chave da API usando um destes métodos:

Método 1: Configuração Smithery (para modo HTTP)
- Ao instalar via Smithery, forneça sua chave de API através do sistema de configuração do Smithery
- A chave é passada por requisição, permitindo cenários multi-usuário
Método 2: Variável de Ambiente (para modo stdio)
```
export RAPID_API_KEY_IMDB=your_api_key_here
```

Ferramentas

Ferramentas de Busca

Ferramenta	Descrição	Exemplo
search_imdb	Busca filmes e séries 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 série 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

Paginado (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 recordes 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 Séries de TV

Paginado (5 resultados por página)

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

Ferramentas de Lançamentos Futuros

Paginado (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_upcoming_releases	Obtém lançamentos futuros de filmes e séries 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

Paginado (5 resultados por página)

Ferramenta	Descrição	Exemplo
get_top_rated_malayalam_movies	Obtém os 50 filmes malaiala mais bem avaliados	`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 telugu em alta	`get_trending_telugu_movies(start=0)`
get_top_rated_tamil_movies	Obtém os 50 filmes tâmeis mais bem avaliados	`get_top_rated_tamil_movies(start=0)`
get_top_rated_telugu_movies	Obtém os 50 filmes telugu mais bem avaliados	`get_top_rated_telugu_movies(start=0)`
get_top_rated_indian_movies	Obtém os 250 filmes indianos mais bem avaliados	`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 filmes de ação que serão lançados em breve:

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 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 1987 em Oakland, CA, 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 os terroristas que mataram sua esposa.

Instalação

Instalando via Smithery (Recomendado)

Para instalar o IMDb Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @uzaysozen/imdb-mcp-server --client claude

Isso configurará automaticamente o servidor com sua chave RapidAPI através do sistema de configuração do Smithery.

Opção 1: Usando Docker

Clone este repositório

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

Construa a imagem Docker

docker build -t imdb_server .

Execute o contêiner Docker

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

Nota: O contêiner Docker executa em modo HTTP por padrão na porta 8081.

Opção 2: Execução Direta em Python (usando uv)

Clone este repositório

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

Instale o uv (se ainda não estiver instalado)

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Instale as dependências usando uv

uv sync

Adicione isto ao seu claude_desktop_config.json:

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

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 (Usado pelo Docker e Smithery)

# 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 a configuração escolhida, reinicie o Claude Desktop para carregar o servidor IMDb. Você poderá então usar todas as ferramentas de dados de filmes e séries de TV em suas conversas com o Claude.

Detalhes Técnicos

O servidor é construído com:

Python 3.13+: Runtime Python moderno
FastMCP: Implementação do servidor com suporte a transporte HTTP e stdio
API IMDb via RapidAPI: Fonte primária de dados
Requests: Biblioteca de comunicação com a API
Smithery: Gerenciamento de configuração e implantação
uv: Gerenciador e executor de pacotes Python rápido
Sistema de cache em memória personalizado: Cache de respostas otimizado com remoção LRU
Paginação inteligente: Limita os resultados a 5 itens por requisição, otimizando para consumo por agentes de IA

Modos de Transporte

O servidor suporta dois modos de transporte:

Modo Stdio (Padrão): Comunicação tradicional do servidor MCP via entrada/saída padrão
- Usado para instalações locais do Claude Desktop
- Configurado via variáveis de ambiente (RAPID_API_KEY_IMDB)
Modo HTTP: Transporte HTTP RESTful com suporte a CORS
- Usado para implantações Docker e Smithery
- Suporta configuração por requisição via sistema de configuração do Smithery
- Executa na porta 8081 por padrão (configurável via variável de ambiente PORT)

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 nos agentes de IA que processam os dados
Resultados Focados: Ajuda os agentes a fornecer informações mais relevantes e concisas aos usuários
Processamento Aprimorado: Reduz a carga cognitiva nos agentes de IA ao analisar dados de filmes e séries 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 requisição com paginação: get_top_250_movies(start=5) retorna os itens 6 a 10

Benefícios

Melhores Respostas dos Agentes: 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 com eficiência
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 eficiente de cache para melhorar o desempenho e reduzir chamadas à API:

Recursos

Cache em Memória: Armazena respostas da 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 uma 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 da API: Ajuda a permanecer dentro dos limites de taxa da API reutilizando respostas
Tempos de Resposta Mais Rápidos: Elimina a 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/main.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

Os limites de taxa da API se aplicam de acordo com sua assinatura RapidAPI
Algumas informações detalhadas podem exigir chamadas adicionais à API
Os resultados da busca podem ser limitados a um certo número de itens por requisiçã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	Modo Stdio: Garanta que a variável de ambiente `RAPID_API_KEY_IMDB` esteja configurada corretamente. Modo HTTP: Verifique se o `rapidApiKeyImdb` é fornecido na configuração do Smithery
Limite de taxa excedido	Verifique seu plano de assinatura e limites do RapidAPI em 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 únicas, 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): `PORT=8082 python src/main.py`
Erros de importação	Garanta que todas as dependências estejam instaladas: `uv sync` ou `pip install mcp[cli] requests smithery`
Conexão recusada (Docker)	Garanta 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.