moviefinder-mcp

MCP-сервер, который оборачивает API The Movie Database (TMDB). Построен с использованием @modelcontextprotocol/sdk и транспорта stdio.

Инструменты

Все инструменты возвращают краткий JSON (id, название, год, описание, рейтинг, URL постера и т. д.) — лишние «сырые» поля TMDB удалены.

Настройка

1. Получите токен API TMDB

1. Создайте бесплатную учетную запись на https://www.themoviedb.org/.

2. Перейдите на https://www.themoviedb.org/settings/api и скопируйте API Read Access Token (v4). Это длинный JWT — это не ключ API v3.

2. Установка и сборка

npm install
npm run build

3. Настройка окружения

Скопируйте .env.example в .env и вставьте свой токен:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Запуск сервера

npm start

Сервер общается по протоколу MCP через stdio и предназначен для запуска MCP-клиентом (например, Claude Desktop), а не для интерактивного использования.

Регистрация в Claude Desktop

Добавьте запись в claude_desktop_config.json:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

После редактирования конфигурации перезапустите Claude Desktop. Инструменты moviefinder появятся в любом диалоге.

Скрипты

Обработка ошибок

Сервер возвращает полезные сообщения при распространенных ошибках TMDB:

• 401 — токен отсутствует или неверный тип ключа (должен быть токен доступа для чтения v4).

• 404 — запрашиваемый фильм / ресурс не существует.

• 429 — превышен лимит запросов; значение Retry-After включается, если оно доступно.

Примечания

• Список жанров загружается один раз из /genre/movie/list и кэшируется в памяти.

• URL постеров используют https://image.tmdb.org/t/p/w500.

• Нет базы данных, нет фреймворка логирования — по замыслу.