MCP Pexels Photo Search

MCP сервер для поиска фотографий по описанию с использованием Pexels API. Сервер автоматически ограничивает поисковый запрос до трех слов для оптимизации результатов.

Описание

Этот MCP (Model Context Protocol) сервер предоставляет инструмент для поиска фотографий через Pexels API. Сервер реализован с использованием TypeScript SDK и работает через стандартный ввод/вывод (stdio), что позволяет интегрировать его с различными MCP клиентами.

Возможности

• 🔍 Поиск фотографий по описанию
• 📝 Автоматическое ограничение запроса до 3 слов
• 🖼️ Возврат метаданных фотографий (URL, фотограф, размеры и т.д.)
• ⚡ Быстрая работа через Pexels API
• 🛠️ Полная поддержка MCP протокола

Установка

Через npm (после публикации)

npm install -g mcp-pexels-photo-search

Локальная установка из исходников

git clone <repository-url>
cd mcp-pexels-photo-search
npm install
npm run build

Важно: Перед использованием сервера (включая локальное тестирование) обязательно установите зависимости командой npm install.

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

Запуск через npx (из npmjs)

После установки пакета из npm, вы можете запустить сервер напрямую:

npx mcp-pexels-photo-search

Локальное тестирование без компиляции

Перед запуском убедитесь, что зависимости установлены:

npm install

Для разработки и тестирования без компиляции TypeScript используйте:

npx tsx src/index.ts

Или используйте npm скрипт:

npm run dev

Запуск после компиляции

npm run build
npm start

Конфигурация для MCP клиентов

Общий формат конфигурации

{
  "mcpServers": {
    "название": {
      "command": "npx",
      "args": ["название пакета на npmjs"],
      "env": {
        "PEXELS_API_KEY": "ваш_api_ключ"
      }
    }
  }
}

Claude Desktop

Добавьте следующую конфигурацию в файл claude_desktop_config.json:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

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

Linux:

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pexels-photo-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pexels-photo-search"
      ],
      "env": {
        "PEXELS_API_KEY": "aC6pdZ2tgZ1mfyqICyi0Ww6A5WUgVqA62nY6YsAqcF3hQEt3QfkecBuv"
      }
    }
  }
}

Примечание: Если переменная окружения PEXELS_API_KEY не указана, будет использован ключ по умолчанию. Для использования собственного API ключа замените значение в секции env.

Локальная конфигурация (для разработки)

Важно: Перед использованием убедитесь, что зависимости установлены в проекте (npm install).

Для локального тестирования без публикации в npm:

{
  "mcpServers": {
    "pexels-photo-search": {
      "command": "npx",
      "args": [
        "tsx",
        "C:\\Users\\ZemAlex\\Desktop\\MCP_site\\src\\index.ts"
      ],
      "cwd": "C:\\Users\\ZemAlex\\Desktop\\MCP_site",
      "env": {
        "PEXELS_API_KEY": "aC6pdZ2tgZ1mfyqICyi0Ww6A5WUgVqA62nY6YsAqcF3hQEt3QfkecBuv"
      }
    }
  }
}

Или используя относительный путь:

{
  "mcpServers": {
    "pexels-photo-search": {
      "command": "npx",
      "args": [
        "tsx",
        "./src/index.ts"
      ],
      "cwd": "C:\\Users\\ZemAlex\\Desktop\\MCP_site",
      "env": {
        "PEXELS_API_KEY": "aC6pdZ2tgZ1mfyqICyi0Ww6A5WUgVqA62nY6YsAqcF3hQEt3QfkecBuv"
      }
    }
  }
}

Примечание: Параметр cwd указывает рабочую директорию, где находятся node_modules с установленными зависимостями.

API

Инструмент: search_photos

Ищет фотографии по описанию используя Pexels API.

Параметры:

• query (string, обязательный) - Описание для поиска фотографий. Максимум 3 слова, остальные будут проигнорированы.

Возвращает:

{
  "query": "sunset mountains",
  "total": 10,
  "photos": [
    {
      "id": 123456,
      "url": "https://images.pexels.com/photos/123456/pexels-photo-123456.jpeg",
      "photographer": "John Doe",
      "photographer_url": "https://www.pexels.com/@johndoe",
      "alt": "Beautiful sunset over mountains",
      "width": 1920,
      "height": 1080,
      "thumbnail": "https://images.pexels.com/photos/123456/pexels-photo-123456.jpeg?auto=compress&cs=tinysrgb&h=350",
      "large": "https://images.pexels.com/photos/123456/pexels-photo-123456.jpeg?auto=compress&cs=tinysrgb&h=650"
    }
  ]
}

Пример использования:

// Через MCP клиент
{
  "method": "tools/call",
  "params": {
    "name": "search_photos",
    "arguments": {
      "query": "beautiful sunset over mountains"
    }
  }
}

Запрос "beautiful sunset over mountains" будет автоматически ограничен до "beautiful sunset over" (первые 3 слова).

API Ключ

Проект использует переменную окружения PEXELS_API_KEY для настройки API ключа Pexels. Если переменная окружения не установлена, используется ключ по умолчанию.

Настройка через переменную окружения (рекомендуется)

Укажите API ключ в конфигурации MCP клиента в секции env:

{
  "mcpServers": {
    "pexels-photo-search": {
      "command": "npx",
      "args": ["-y", "mcp-pexels-photo-search"],
      "env": {
        "PEXELS_API_KEY": "ваш_api_ключ_здесь"
      }
    }
  }
}

Получение собственного API ключа

1. Зарегистрируйтесь на Pexels
2. Получите API ключ в разделе API
3. Укажите его в конфигурации MCP клиента через переменную окружения PEXELS_API_KEY

Примечание: Использование переменной окружения более безопасно, чем хардкодинг ключа в коде.

Разработка

Требования

• Node.js >= 18.0.0
• npm или yarn

Установка зависимостей

npm install

Сборка проекта

npm run build

Запуск в режиме разработки

npm run dev

Структура проекта

mcp-pexels-photo-search/
├── src/
│   └── index.ts          # Основной файл MCP сервера
├── dist/                 # Скомпилированные файлы (после build)
├── package.json          # Конфигурация npm пакета
├── tsconfig.json         # Конфигурация TypeScript
├── README.md             # Документация
└── LICENSE               # Лицензия MIT

Публикация на npm

1. Убедитесь, что версия в package.json обновлена
2. Войдите в npm:

   npm login

3. Опубликуйте пакет:

   npm publish

Лицензия

MIT

Автор

Разработано для поиска фотографий через Pexels API с использованием Model Context Protocol.

Поддержка

При возникновении проблем создайте issue в репозитории проекта.