TMDB MCP Server

Acesse informações de filmes, buscas e recomendações da API do The Movie Database (TMDB).

Documentação

Servidor MCP TMDB

Um servidor MCP para a API do The Movie Database (TMDB). Ele fornece busca de filmes e séries, disponibilidade de streaming, detalhes de elenco e equipe, e recomendações para assistentes como Codex e Claude Desktop.

Para a divisão de arquitetura entre o servidor MCP reutilizável e os fluxos de trabalho de recursos de nível superior, consulte USERGUIDE.md.

Ferramentas

Descoberta de Filmes

get_weekend_watchlist — Lista curta classificada de fim de semana por humor, país, idioma, duração, avaliação e serviços
plan_watch_party — Plano de noite de cinema em grupo com uma escolha principal, reserva, curinga, motivos de adequação ao grupo, disponibilidade de provedores e filtragem de títulos evitados
build_franchise_watch_order — Guia de franquia/universo com ordem de lançamento, ordem sugerida, duração total e notas com informações de provedores
build_collection_gap_plan — Plano de conclusão de franquia com entradas assistidas/faltantes, duração restante, disponibilidade de provedores e caminho de conclusão
recommend_from_taste_profile — Recomendações de títulos curtidos/não curtidos com pontuação com informações de provedores, motivos de correspondência e alertas
build_release_calendar_watchlist — Lista de observação de janela de lançamento com filmes futuros, escolhas prontas para provedores, linhas de base para grupos amplos e pontuação para assistir depois
search_movies — Busca por título/palavras-chave → títulos, IDs, avaliações, resumos
get_trending — Top 10 filmes em tendência (timeWindow: "day" | "week")
get_weekly_trending_by_language — Filmes em tendência semanal agrupados por idioma original em inglês, hindi e telugu
search_by_genre — Filmes por nome de gênero, filtro opcional de ano
advanced_search — Filtrar por gênero, ano, avaliação mínima, ordenação, idioma
search_by_keyword — Encontrar filmes por tema/palavra-chave (ex.: "zumbi", "assalto")

Detalhes de Filmes

get_movie_details — Detalhes completos: elenco, equipe, duração, gêneros, críticas (por movieId)
compare_movies — Comparação lado a lado para 2-5 IDs de filmes com avaliações, duração, elenco, diretor, provedores e notas de melhor adequação
get_recommendations — Top 5 recomendações com base em um ID de filme
get_similar_movies — Filmes semelhantes via algoritmo de similaridade do TMDB
get_watch_providers — Disponibilidade de streaming/aluguel/compra por país (padrão: IN)
find_where_to_watch — Buscar 1-5 títulos de filmes e retornar disponibilidade de streaming/aluguel/compra com correspondências de serviços preferidos

Séries de TV

search_tv_shows — Buscar séries de TV por título
get_trending_tv — Top 10 séries de TV em tendência (timeWindow: "day" | "week")

Pessoas

search_person — Encontrar atores, diretores, equipe por nome → ID + obras conhecidas
get_person_details — Biografia completa + filmografia (filmes + TV) por personId
build_person_watch_path — Caminho de observação de ator/diretor com escolhas mais bem avaliadas, disponíveis agora, recentes e iniciais

Recursos

tmdb:///movie/<id> — Detalhes completos do filme em JSON (título, elenco, diretor, críticas, URL do pôster)

Início Rápido

Obtenha uma chave de API TMDB em themoviedb.org → Configurações da Conta → API

Clone, instale e compile:

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

Crie um arquivo env local e adicione sua chave TMDB:
```
cp .env.example .env
```
Instale a integração local do Codex e do Claude Desktop:
```
npm run install:local
```
Reinicie o Codex ou o Claude Desktop se já estiverem abertos.
Verifique com um prompt como:
```
What movies are trending this week?
```

No Codex, uma nova sessão deve mostrar TMDB na lista de plugins e expor o namespace mcp__tmdb__.

Teste Rápido da Superfície de Ferramentas

Use este teste rápido após adicionar ou mesclar ferramentas. Ele verifica o contrato esperado da ferramenta MCP e chama as principais ferramentas de fluxo de trabalho: compare_movies, find_where_to_watch, get_weekend_watchlist, plan_watch_party, build_franchise_watch_order, build_collection_gap_plan, recommend_from_taste_profile e build_person_watch_path.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

MCP hospedado no 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

O script grava um artefato de verificação compacto em:

examples/tool-surface-smoke.md

Para evitar inchaço de ferramentas, prefira adicionar ferramentas de fluxo de trabalho que combinem várias chamadas TMDB em uma decisão útil para o usuário. Mantenha ferramentas de estilo endpoint bruto apenas quando forem primitivas amplamente reutilizáveis.

Demonstração de Tendências Semanais por Idioma

Este repositório inclui uma pequena demonstração compartilhável que chama a ferramenta MCP get_weekly_trending_by_language, que busca filmes em tendência semanal ao vivo do TMDB e agrupa a primeira página atual por original_language do TMDB.

Execute-a contra o servidor MCP stdio local:

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

Após implantar esta versão do Worker, execute a mesma demonstração contra um 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

Se a implantação for intencionalmente sem autenticação para testes pessoais, omita TMDB_MCP_ACCESS_TOKEN.

Radar Semanal de Streaming

Este repositório também inclui um radar semanal com foco em script. Ele encadeia ferramentas MCP existentes em um artefato Markdown com tendências de filmes, tendências de TV, impulso de idiomas, escolhas prontas para ação, escolhas seguras para a família e uma sonda de perfil de gosto.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-radar -- --country US

MCP hospedado no Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-streaming-radar.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US

O script grava:

examples/weekly-streaming-radar.md

Lista de Observação do Calendário de Lançamentos

O calendário de lançamentos está disponível como a ferramenta MCP build_release_calendar_watchlist. O script de demonstração chama essa ferramenta e grava um artefato Markdown para varredura de janela de lançamento, candidatos para assistir depois, escolhas prontas para provedores e linhas de base para grupos amplos.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:release-calendar -- --country US --days 90

MCP hospedado no Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/release-calendar-watchlist.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --days 90

O script grava:

examples/release-calendar-watchlist.md

Monitor de Mudanças de Provedores

O monitor de provedores é baseado em script porque precisa de estado persistido. Ele chama find_where_to_watch, compara a lista atual de provedores com um instantâneo JSON e grava um relatório de diferenças em Markdown mostrando disponibilidade de provedores nova, removida, inalterada e ausente.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:provider-monitor -- --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

MCP hospedado no Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/provider-change-monitor.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

O script grava:

examples/provider-change-monitor.md
examples/provider-change-snapshot.json

Localizador de Lacunas de Coleção

O script do localizador de lacunas de coleção agora chama a ferramenta MCP promovida build_collection_gap_plan e grava um relatório de conclusão Markdown repetível com entradas assistidas, entradas faltantes, duração restante, disponibilidade de provedores e o caminho de conclusão mais curto.

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:collection-gaps -- --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

MCP hospedado no Cloudflare:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/collection-gap-finder.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

O script grava:

examples/collection-gap-finder.md

MCP Remoto no Cloudflare Workers

Este repositório também pode ser executado como um servidor MCP remoto no Cloudflare Workers. O servidor remoto expõe as mesmas ferramentas TMDB em /mcp via Streamable HTTP, para que Claude, Cowork, conectores Claude Desktop e outros clientes MCP remotos possam se conectar a uma URL pública.

O servidor stdio local existente permanece inalterado para uso com Codex e Claude Desktop local. O ponto de entrada do Cloudflare é src/worker.ts.

O Worker também serve uma demonstração de navegador em /: Weekend Watch Concierge. Ele suporta escolhas individuais e modo Watch Party, e então constrói uma lista curta classificada de filmes usando descoberta TMDB, tendências, agora em exibição, créditos, pôsteres e dados de provedores de streaming. O aplicativo de navegador também inclui uma gaveta de Ajuda para uso do Cloudflare e um painel de Demonstrações de Fluxo de Trabalho com comandos para artefatos baseados em script, como Radar Semanal de Streaming, Monitor de Mudanças de Provedores e Localizador de Lacunas de Coleção.

A demonstração de navegador também inclui um painel de superfície de ferramentas MCP que chama a rota /mcp implantada, verifica o contrato esperado da ferramenta e amostra compare_movies, find_where_to_watch, get_weekend_watchlist, plan_watch_party, build_franchise_watch_order, build_collection_gap_plan, recommend_from_taste_profile e build_person_watch_path.

Para o aplicativo de navegador completo, Worker implantado, token de acesso e handoff MCP, consulte docs/weekend-watch-concierge.md.

Implantar

Faça login no Cloudflare:
```
npx wrangler login
```
Armazene sua chave TMDB como um segredo do Worker:
```
npx wrangler secret put TMDB_API_KEY
```
Armazene um token de acesso como um segredo do Worker antes de compartilhar a implantação:
```
npx wrangler secret put ACCESS_TOKEN
```
Quando ACCESS_TOKEN estiver definido, POST /api/concierge e POST /mcp exigem:
```
Authorization: Bearer <your-access-token>
```
Verifique o pacote do Worker:
```
npm run worker:dry-run
```
Implante:
```
npm run worker:deploy
```

O Cloudflare imprimirá uma URL como:

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

Use este endpoint MCP em clientes remotos:

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

Use esta URL de demonstração de navegador:

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

Conectar a partir do Claude / Cowork

Para conectores personalizados do Claude:

Abra as configurações do Claude: Customize -> Connectors.
Clique em + -> Add custom connector.

Use a URL MCP do Worker implantado:

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

Ative o conector em uma conversa e faça uma pergunta sobre TMDB, como:
```
What movies are trending this week?
```

Para versões do Claude Desktop ou clientes MCP que ainda exigem um comando local, use o proxy mcp-remote:

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

Nota de segurança

Se ACCESS_TOKEN não estiver configurado, o Worker fica sem autenticação para facilitar testes pessoais. Qualquer pessoa que tenha a URL do Worker pode chamar as ferramentas TMDB somente leitura e consumir sua cota da API TMDB. Mantenha ACCESS_TOKEN configurado ou use o Cloudflare Access antes de compartilhar além de suas próprias contas.

Weekend Watch Concierge

Execute o teste offline do concierge:

npm test

Isso compila o projeto TypeScript, inicia um pequeno servidor fixture local compatível com TMDB e verifica se createWeekendConcierge classifica uma correspondência de serviço de streaming solicitada em primeiro lugar, respeitando o filtro de duração. Não precisa de chave de API TMDB.

Execute o Worker localmente:

npm run worker:dev

Isso sincroniza valores locais de .env em um arquivo .dev.vars não rastreado para que o Wrangler possa expor TMDB_API_KEY ao Worker durante o desenvolvimento local.

Para testes locais protegidos, adicione ACCESS_TOKEN a .env. O aplicativo de navegador tem um campo de token de acesso e os scripts de teste rápido podem ler ACCESS_TOKEN ou TMDB_MCP_ACCESS_TOKEN do ambiente do shell.

Abra:

http://127.0.0.1:8787/

Teste rapidamente a API do concierge após o Worker local estar em execução:

npm run smoke:concierge

Teste rapidamente o endpoint MCP remoto e chame a ferramenta concierge voltada para agentes:

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

Para uma implantação protegida:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

Ou teste um Worker implantado:

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

O aplicativo usa:

POST /api/concierge para escolhas de filmes classificadas
POST /api/collection-gap-plan para lacunas de coleção do Planning Lab
POST /api/taste-profile para recomendações de adequação de gosto do Planning Lab
POST /api/person-watch-path para caminhos de observação de pessoas do Planning Lab
GET /health para saúde da implantação
POST /mcp para clientes MCP remotos

Agentes podem chamar get_weekend_watchlist com:

mood: crowd, thriller, thoughtful, funny, family ou mindbend
country: região do provedor de streaming, por exemplo IN ou US
language: código do idioma original, por exemplo en, hi, ta, te ou any
runtime: duração máxima em minutos, por exemplo 120, 150 ou any
minRating: avaliação mínima do TMDB
services: serviços de streaming preferidos
familySafe: defina como true para excluir gêneros maduros comuns quando os dados de gênero do TMDB estiverem disponíveis

Agentes podem chamar plan_watch_party quando a decisão for para um grupo. Ele aceita:

moods: um a três valores de crowd, thriller, thoughtful, funny, family ou mindbend
groupSize: número de pessoas assistindo
country, language, runtime, minRating e services: mesmo significado da lista de fim de semana
avoidTitles: títulos que o grupo já viu ou deseja excluir
familySafe: defina como true para excluir gêneros maduros comuns quando os dados de gênero do TMDB estiverem disponíveis

Agentes podem chamar build_franchise_watch_order para um guia de coleção ou universo. Ele aceita:

query: nome da franquia ou coleção, por exemplo The Matrix, Dune, Batman ou Mission Impossible
country: região do provedor de streaming, por exemplo IN ou US
maxMovies: número máximo de entradas de coleção a incluir, de 2 a 20

Agentes podem chamar build_collection_gap_plan para planejamento de conclusão de franquia. Ele aceita:

query: nome da franquia ou coleção
watchedTitles: títulos assistidos ou IDs de filmes do TMDB
country: região do provedor de streaming, por exemplo IN ou US
services: serviços de streaming preferidos
maxMovies: número máximo de entradas da coleção a incluir, de 2 a 20

Agentes podem chamar recommend_from_taste_profile para recomendações personalizadas. Ele aceita:

likedTitles: de um a cinco filmes que o usuário gosta
dislikedTitles: filmes opcionais que o usuário não gosta ou quer evitar estilisticamente
country, services, language, runtime e minRating: filtros e preferências de assistir agora
maxResults: número de recomendações a retornar, de 3 a 10

Agentes podem chamar build_person_watch_path para um ator, diretor, roteirista ou membro da equipe. Ele aceita:

name: nome da pessoa, por exemplo Keanu Reeves ou Christopher Nolan
country: região do provedor de streaming, por exemplo IN ou US
services: serviços de streaming preferidos
maxTitles: número de entradas do caminho de exibição a retornar, de 3 a 8

Fluxo de Trabalho da Demonstração Cloudflare MCP

Para um fluxo de trabalho de agente completo e de ponta a ponta, execute a demonstração de acompanhamento de filmes em cartaz. Ela usa o servidor MCP como um cliente remoto faria:

get_now_playing para descoberta de filmes em cartaz em uma região selecionada
get_movie_details para o título selecionado
get_watch_providers para disponibilidade de assistir agora
get_recommendations, com fallback get_similar_movies para títulos muito recentes
get_watch_providers para verificações de disponibilidade de acompanhamento

MCP stdio local:

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

MCP hospedado na 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

O script grava o artefato final aqui:

examples/now-playing-follow-on-demo.md

O que o `npm run install:local` faz

O instalador usa o launcher de propriedade do repositório em plugins/tmdb/scripts/run-server.sh.

Para Codex, ele:

Registra o launcher como um servidor MCP
Instala um payload de plugin local TMDB para que apareça na interface do plugin

Para Claude Desktop, ele:

Registra o mesmo launcher como um servidor MCP local

Ele atualiza:

~/.codex/config.toml
~/.codex/.tmp/plugins/.agents/plugins/marketplace.json
~/.codex/plugins/cache/openai-curated/tmdb/...
~/Library/Application Support/Claude/claude_desktop_config.json

O launcher lê TMDB_API_KEY do seu ambiente de shell ou do arquivo .env do repositório.

Uso com Claude Desktop

Se você preferir configuração manual, adicione 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": []
    }
  }
}

Reinicie o Claude Desktop após editar a configuração.

Uso com Codex

O instalador adiciona estes blocos à ~/.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

Reinicie o Codex após editar a configuração. Em uma nova sessão do Codex, TMDB deve aparecer na lista de plugins e contribuir com o namespace mcp__tmdb__.

Validação

Teste de fumaça offline:

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

Teste de fumaça online:

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

Documentação do Plugin

Para empacotamento de plugins, comportamento de instalação local e notas específicas do Codex, consulte plugins/tmdb/README.md.

Uso com BizClaw / NanoClaw

Integrado ao contêiner do agente. Basta definir TMDB_API_KEY no seu arquivo .env — nenhuma configuração é necessária.

Exemplos 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?"

Licença

MIT

TMDB MCP Server

Documentação

Servidor MCP TMDB

Ferramentas

Descoberta de Filmes

Detalhes de Filmes

Séries de TV

Pessoas

Recursos

Início Rápido

Teste Rápido da Superfície de Ferramentas

Demonstração de Tendências Semanais por Idioma

Radar Semanal de Streaming

Lista de Observação do Calendário de Lançamentos

Monitor de Mudanças de Provedores

Localizador de Lacunas de Coleção

MCP Remoto no Cloudflare Workers

Implantar

Conectar a partir do Claude / Cowork

Nota de segurança

Weekend Watch Concierge

Fluxo de Trabalho da Demonstração Cloudflare MCP

O que o npm run install:local faz

Uso com Claude Desktop

Uso com Codex

Validação

Documentação do Plugin

Uso com BizClaw / NanoClaw

Exemplos de Prompts

Licença

O que o `npm run install:local` faz