mcp-server-pexels

MCP-сервер для поиска стоковых фотографий и видео на Pexels. Оптимизирован для LLM.

Pexels предоставляет бесплатные стоковые фотографии и видео.

Возможности

• Поиск фото — Поиск фотографий с фильтрами (запрос, ориентация, размер, цвет, локаль)

• Поиск видео — Поиск видео, автоматический выбор HD .mp4, наиболее близкого к 1920x1080

• Получение деталей — Получение полных метаданных для фото/видео по ID

• Интеллектуальное кэширование — TTL 10 минут для поиска, 60 минут для поиска по ID

• Обработка ошибок — Корректная обработка с полезными сообщениями (согласно лучшим практикам MCP)

• Атрибуция — Обязательное указание автора в каждом результате

Системные требования

• Node.js v20+

• API-ключ Pexels (бесплатно на pexels.com/api)

Быстрый старт (2 минуты)

1. Получите API-ключ

Зарегистрируйтесь на pexels.com/api — бесплатно, кредитная карта не требуется.

2. Соберите сервер

npm install && npm run build

3. Добавьте в Claude Desktop

Откройте ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) или %APPDATA%\Claude\claude_desktop_config.json (Windows) и добавьте:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-pexels/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_PEXELS_API_KEY"
      }
    }
  }
}

Примечание для Windows: Используйте полный путь к node.exe или добавьте Node в PATH. Прямые слэши в путях работают в Windows.

4. Перезапустите Claude Desktop

Сервер теперь доступен как pexels_search_photos, pexels_search_videos и pexels_get_details.

Конфигурация

Добавьте в ваш .mcp.json или claude_desktop_config.json:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Окружение

Установите PEXELS_API_KEY в вашем окружении. Для локальной разработки создайте файл .env:

PEXELS_API_KEY=your_pexels_api_key

Разработка

npm run dev      # watch mode
npm run inspector # MCP Inspector
npm test          # run tests

Инструменты

Архитектура

• src/index.ts — Точка входа, настройка MCP-сервера

• src/tools/ — Реализация инструментов

• src/shared/ — Кэш, API-клиент, ошибки, типы, выбор видео

• src/utils/ — Схемы валидации Zod

Инженерные решения

Совместимость

Протестировано с @modelcontextprotocol/sdk v1.29+ через StdioClientTransport. Набор интеграционных тестов запускает собранный сервер и проверяет каждый вызов инструмента на соответствие CallToolResultSchema и ContentBlockSchema SDK.

Структурированный JSON-блок добавляется как последний элемент контента в каждом успешном ответе, содержащий типизированные данные (id, kind, creatorName, dimensions, URLs). Клиенты и агентские фреймворки могут парсить этот блок напрямую, вместо использования регулярных выражений для текста markdown.

Будущие улучшения

• Телеметрия выполнения инструментов — Добавить структурированное логирование попаданий/промахов кэша, времени выполнения запроса и частоты ошибок. Это помогает в отладке ИИ-агентов в продакшене и демонстрирует лучшие практики наблюдаемости.

• Эндпоинт метрик — Предоставить счетчики (обслуженные запросы, коэффициент попаданий в кэш, оставшаяся квота API) для мониторинга.

• Настраиваемый TTL — Позволить пользователям настраивать TTL кэша через переменные окружения.

Вклад сообщества

• приветствуется! 🌟

Лицензия

Неофициальный проект сообщества. Не связан с Pexels.