TMDB MCP Server

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

Инструменты

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

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

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

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

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

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

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

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

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

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

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

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

Телесериалы

• 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: TMDB MCP Server

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

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 на Cloudflare Workers

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

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

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

Полную информацию о браузерном приложении, развернутом 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, прежде чем делиться этим за пределами своих собственных аккаунтов.

Консьерж для выбора фильмов на выходные

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

npm run worker:dev

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

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

Откройте:

http://127.0.0.1:8787/

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

npm run smoke:concierge

Проведите smoke-тестирование удаленного 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: предпочтительные стриминговые сервисы

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

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

Для Codex он:

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

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

Для 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__.

Валидация

Офлайн smoke-тест:

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

Онлайн smoke-тест:

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