TMDB MCP Server

MCP-сервер для API The Movie Database (TMDB). Он предоставляет возможности поиска фильмов и сериалов, информацию о доступности на стриминговых сервисах, сведения об актерах и съемочной группе, а также рекомендации для таких ассистентов, как Codex и Claude Desktop.

Инструменты

Поиск фильмов

• get_weekend_watchlist — Ранжированный список фильмов на выходные по настроению, стране, языку, длительности, рейтингу и сервисам

• search_movies — Поиск по названию/ключевым словам → названия, ID, рейтинги, описания

• get_trending — Топ-10 популярных фильмов (timeWindow: "day" | "week")

• get_weekly_trending_by_language — Еженедельные популярные фильмы, сгруппированные по оригинальному языку: английский, хинди и телугу

• search_by_genre — Фильмы по названию жанра, опциональный фильтр по году

• advanced_search — Фильтрация по жанру, году, минимальному рейтингу, сортировке, языку

• search_by_keyword — Поиск фильмов по теме/ключевому слову (например, "zombie", "heist")

Детали фильма

• get_movie_details — Полная информация: актеры, съемочная группа, длительность, жанры, отзывы (по movieId)

• compare_movies — Сравнение 2-5 фильмов по ID с указанием рейтингов, длительности, актеров, режиссера, провайдеров и примечаний о соответствии

• get_recommendations — Топ-5 рекомендаций на основе ID фильма

• get_similar_movies — Похожие фильмы через алгоритм сходства TMDB

• get_watch_providers — Доступность для просмотра/аренды/покупки по странам (по умолчанию: IN)

• find_where_to_watch — Поиск 1-5 названий фильмов и возврат информации о доступности для просмотра/аренды/покупки с учетом предпочтительных сервисов

Сериалы

• search_tv_shows — Поиск сериалов по названию

• get_trending_tv — Топ-10 популярных сериалов (timeWindow: "day" | "week")

Люди

• search_person — Поиск актеров, режиссеров, съемочной группы по имени → ID + известные работы

• get_person_details — Полная биография + фильмография (фильмы + сериалы) по personId

Ресурсы

• tmdb:///movie/<id> — Полная информация о фильме в формате JSON (название, актеры, режиссер, отзывы, URL постера)

Related MCP server: Usher MCP

Быстрый старт

1. Получите API-ключ TMDB на themoviedb.org → Настройки аккаунта → API

2. Клонируйте, установите и соберите:

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

3. Создайте локальный файл окружения и добавьте свой ключ TMDB:

   cp .env.example .env

4. Установите локальную интеграцию с Codex и Claude Desktop:

   npm run install:local

5. Перезапустите Codex или Claude Desktop, если они уже открыты.

6. Проверьте с помощью запроса, например:

   What movies are trending this week?

В Codex в новой сессии в списке плагинов должен появиться TMDB, открывающий пространство имен mcp__tmdb__.

Дымовое тестирование инструментов

Используйте этот дымовой тест после добавления или объединения инструментов. Он проверяет ожидаемый контракт инструментов MCP и вызывает основные рабочие инструменты: compare_movies, find_where_to_watch и get_weekend_watchlist.

Локальный stdio MCP:

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

MCP на базе 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

Скрипт записывает компактный артефакт проверки в:

examples/tool-surface-smoke.md

Чтобы избежать перегрузки инструментов, отдавайте предпочтение добавлению рабочих инструментов, которые объединяют несколько вызовов TMDB в полезное для пользователя решение. Оставляйте инструменты в стиле «сырых» эндпоинтов только тогда, когда они являются широко применимыми примитивами.

Демонстрация еженедельных трендов по языкам

Этот репозиторий включает небольшое демо, которое вызывает инструмент MCP get_weekly_trending_by_language, получающий актуальные еженедельные тренды TMDB и группирующий текущую первую страницу по original_language TMDB.

Запустите его против локального stdio MCP-сервера:

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

После развертывания этой версии Worker, запустите то же демо против удаленного эндпоинта MCP:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

Если развертывание намеренно не требует аутентификации для личного тестирования, опустите TMDB_MCP_ACCESS_TOKEN.

Удаленный MCP на Cloudflare Workers

Этот репозиторий также может работать как удаленный MCP-сервер на Cloudflare Workers. Удаленный сервер предоставляет те же инструменты TMDB по адресу /mcp через Streamable HTTP, поэтому Claude, Cowork, коннекторы Claude Desktop и другие удаленные MCP-клиенты могут подключаться к публичному URL.

Существующий локальный stdio-сервер остается без изменений для использования в Codex и локальном Claude Desktop. Точка входа Cloudflare — src/worker.ts.

Worker также обслуживает браузерное демо по адресу /: Weekend Watch Concierge. Он запрашивает настроение, страну, язык, длительность, рейтинг и стриминговые сервисы, а затем составляет ранжированный список фильмов, используя данные TMDB о фильмах, трендах, текущих показах, титрах, постерах и провайдерах.

Браузерное демо также включает панель поверхности инструментов MCP, которая вызывает развернутый маршрут /mcp, проверяет ожидаемый контракт инструментов и тестирует compare_movies, find_where_to_watch и get_weekend_watchlist.

Полное описание браузерного приложения, развернутого Worker, токена доступа и передачи MCP см. в docs/weekend-watch-concierge.md.

Развертывание

1. Войдите в Cloudflare:

   npx wrangler login

2. Сохраните свой ключ TMDB как секрет Worker:

   npx wrangler secret put TMDB_API_KEY

3. Сохраните токен доступа как секрет Worker перед тем, как делиться развертыванием:

   npx wrangler secret put ACCESS_TOKEN

   Когда установлен ACCESS_TOKEN, POST /api/concierge и POST /mcp требуют:

   Authorization: Bearer <your-access-token>

4. Проверьте сборку Worker:

   npm run worker:dry-run

5. Разверните:

   npm run worker:deploy

Cloudflare выведет URL, например:

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

Используйте этот эндпоинт MCP в удаленных клиентах:

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

Используйте этот URL браузерного демо:

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

Подключение из Claude / Cowork

Для пользовательских коннекторов Claude:

1. Откройте настройки Claude: Customize -> Connectors.

2. Нажмите + -> Add custom connector.

3. Используйте URL развернутого Worker MCP:

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

4. Включите коннектор в диалоге и задайте вопрос по TMDB, например:

   What movies are trending this week?

Для версий Claude Desktop или MCP-клиентов, которые все еще требуют локальную команду, используйте прокси mcp-remote:

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

Примечание по безопасности

Если ACCESS_TOKEN не настроен, Worker работает без аутентификации для простого личного тестирования. Любой, у кого есть URL Worker, может вызывать инструменты TMDB только для чтения и расходовать вашу квоту API TMDB. Настройте ACCESS_TOKEN или используйте Cloudflare Access перед тем, как делиться этим за пределами своих аккаунтов.

Weekend Watch Concierge

Запустите офлайн-тест консьержа:

npm test

Это собирает проект TypeScript, запускает крошечный локальный сервер-фиксатор, совместимый с TMDB, и проверяет, что createWeekendConcierge ранжирует запрошенное совпадение стримингового сервиса первым, соблюдая фильтр длительности. API-ключ TMDB не требуется.

Запустите Worker локально:

npm run worker:dev

Это синхронизирует локальные значения из .env в неотслеживаемый файл .dev.vars, чтобы Wrangler мог предоставить TMDB_API_KEY для Worker во время локальной разработки.

Для защищенного локального тестирования добавьте ACCESS_TOKEN в .env. В браузерном приложении есть поле для токена доступа, а дымовые скрипты могут считывать ACCESS_TOKEN или TMDB_MCP_ACCESS_TOKEN из окружения оболочки.

Откройте:

http://127.0.0.1:8787/

Проведите дымовое тестирование API консьержа после запуска локального Worker:

npm run smoke:concierge

Проведите дымовое тестирование удаленного эндпоинта MCP и вызовите инструмент консьержа для агента:

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

Для защищенного развертывания:

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

Или протестируйте развернутый Worker:

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

Приложение использует:

• POST /api/concierge для ранжированных подборок фильмов

• GET /health для проверки работоспособности развертывания

• POST /mcp для удаленных MCP-клиентов

Агенты могут вызывать get_weekend_watchlist с параметрами:

• mood: crowd, thriller, thoughtful, funny, family или mindbend

• country: регион провайдера, например IN или US

• language: код оригинального языка, например en, hi, ta, te или any

• runtime: максимальное количество минут, например 120, 150 или any

• minRating: минимальный рейтинг TMDB

• services: предпочтительные стриминговые сервисы

Рабочий процесс демо Cloudflare MCP

Для конкретного сквозного рабочего процесса агента запустите демо с последующими действиями по текущим показам. Оно использует MCP-сервер так, как это делал бы удаленный клиент:

1. get_now_playing для поиска текущих кинотеатральных показов в выбранном регионе

2. get_movie_details для выбранного названия

3. get_watch_providers для проверки доступности «смотреть сейчас»

4. get_recommendations с резервным вариантом get_similar_movies для очень новых фильмов

5. get_watch_providers для последующих проверок доступности

Локальный stdio MCP:

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

MCP на базе 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

Скрипт записывает финальный артефакт здесь:

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

Что делает npm run install:local

Установщик использует лаунчер репозитория по адресу plugins/tmdb/scripts/run-server.sh.

Для Codex он:

• Регистрирует лаунчер как MCP-сервер

• Устанавливает локальный полезный груз плагина TMDB, чтобы он появился в UI плагинов

Для Claude Desktop он:

• Регистрирует тот же лаунчер как локальный MCP-сервер

Он обновляет:

• ~/.codex/config.toml

• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json

• ~/.codex/plugins/cache/openai-curated/tmdb/...

• ~/Library/Application Support/Claude/claude_desktop_config.json

Лаунчер считывает TMDB_API_KEY из окружения вашей оболочки или из файла .env репозитория.

Использование с Claude Desktop

Если вы предпочитаете ручную настройку, добавьте в ~/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": []
    }
  }
}

Перезапустите Claude Desktop после редактирования конфигурации.

Использование с Codex

Установщик добавляет эти блоки в ~/.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

Перезапустите Codex после редактирования конфигурации. В новой сессии Codex TMDB должен появиться в списке плагинов и добавить пространство имен mcp__tmdb__.

Валидация

Офлайн дымовой тест:

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

Онлайн дымовой тест:

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

Документация плагина

Информацию об упаковке плагина, поведении при локальной установке и примечания для Codex см. в plugins/tmdb/README.md.

Использование с BizClaw / NanoClaw

Встроено в контейнер агента. Просто установите TMDB_API_KEY в вашем файле .env — настройка не требуется.

Примеры запросов

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

Лицензия

MIT