de en es ja ko ru zh

mcp-server-pexels

Name: mcp-server-pexels
Author: afshinator

by afshinator

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

mcp-server-pexels

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

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

Возможности

Поиск фото — Поиск фотографий с фильтрами (запрос, ориентация, размер, цвет, локаль)
Поиск видео — Поиск видео, автоматический выбор HD .mp4, наиболее близкого к 1920x1080
Получение деталей — Получение полных метаданных для фото/видео по ID
Интеллектуальное кэширование — TTL 10 минут для поиска, 60 минут для поиска по ID
Обработка ошибок — Корректная обработка с полезными сообщениями (согласно лучшим практикам MCP)
Атрибуция — Обязательное указание автора в каждом результате

Related MCP server: Pexels MCP Server

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

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

Инструменты

Инструмент	Описание
`pexels_search_photos`	Поиск фотографий по запросу
`pexels_search_videos`	Поиск видео
`pexels_get_details`	Получение деталей по ID и типу

Архитектура

src/index.ts — Точка входа, настройка MCP-сервера
src/tools/ — Реализация инструментов
src/shared/ — Кэш, API-клиент, ошибки, типы, выбор видео
src/utils/ — Схемы валидации Zod

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

Решение	Обоснование
Архитектура с приоритетом кэша	API Pexels разрешает 200 запросов в час. Кэширование (TTL 10 мин для поиска, 60 мин для ID) экономит квоту, снижает задержку до <5 мс при попадании в кэш и демонстрирует понимание стоимости API — критически важно для производственных ИИ-систем, где агенты часто запрашивают один и тот же контекст.
Быстрый отказ при вызове	MCP-серверы запускаются как дочерние процессы — запуск не лучшее время для сбоя. Сервер предупреждает при запуске, но корректно завершается при первом вызове инструмента с `isError: true`.
Схемы валидации Zod	MCP v2 SDK требует обертки `z.object()`. Перехватывает неверный ввод до того, как он попадет в API.
resource_link для медиа	Удаленные изображения и видео предоставляются как блоки контента `resource_link` в MCP с правильным mimeType. Markdown-ссылка на изображение в текстовом блоке остается как резервный вариант для клиентов, которые не отображают `resource_link`.
Чистый выбор видео	Логика выбора видео изолирована в `video-selector.ts` — тестируется независимо от обработчика инструментов.
Жестко заданная атрибуция	Требуется Условиями использования Pexels. Встроена в каждый текстовый ответ.

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

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

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

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

Телеметрия выполнения инструментов — Добавить структурированное логирование попаданий/промахов кэша, времени выполнения запроса и частоты ошибок. Это помогает в отладке ИИ-агентов в продакшене и демонстрирует лучшие практики наблюдаемости.
Эндпоинт метрик — Предоставить счетчики (обслуженные запросы, коэффициент попаданий в кэш, оставшаяся квота API) для мониторинга.
Настраиваемый TTL — Позволить пользователям настраивать TTL кэша через переменные окружения.

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

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

Лицензия

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

Available Tools

3 tools

pexels_get_detailsGet Pexels DetailsA

Read-onlyIdempotent

Get detailed information about a specific photo or video by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`type`	Yes
`force_refresh`	No

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds that it returns 'detailed information' but does not disclose any additional behavioral traits like rate limits or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with three parameters and no output schema, the description is minimally adequate. It fails to hint at the output format or behavior of the optional 'force_refresh' parameter, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate. It only mentions 'by ID', leaving parameters like 'type' and 'force_refresh' unexplained. While the enum for type provides some guidance, the description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Get', resource 'detailed information about a specific photo or video', and method 'by ID'. It effectively distinguishes from sibling search tools (pexels_search_photos, pexels_search_videos) which query by keywords.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a specific ID is known, contrasting with search tools. However, it does not explicitly state when not to use it or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_photosSearch Pexels PhotosA

Read-onlyIdempotent

Search for stock photos by query with optional filters for orientation, size, color, and locale. Returns 3-5 results with mandatory photographer attribution.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`orientation`	No
`size`	No
`color`	No
`locale`	No
`per_page`	No
`force_refresh`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`kind`	Yes
`creatorName`	Yes
`creatorUrl`	Yes
`pageUrl`	Yes
`previewUrl`	Yes
`mediaUrl`	Yes
`mediaMimeType`	Yes
`dimensions`	Yes
`avgColor`	Yes
`alt`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral details: returns 3-5 results and requires photographer attribution, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, extremely concise, with no filler. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and annotations, the description covers core functionality well. It lacks mention of per_page and force_refresh, but is otherwise sufficient for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions four optional filters (orientation, size, color, locale), adding semantic context that they are filters. However, it omits per_page and force_refresh, and schema coverage is 0%. The added value is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for stock photos by query with optional filters', specifying verb and resource. It distinguishes from siblings (pexels_get_details for individual photos, pexels_search_videos for videos) by focusing on photo search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus its siblings or alternatives. Usage is implied but not contrasted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_videosSearch Pexels VideosA

Read-onlyIdempotent

Search for stock videos by query with optional filters. Returns HD-quality .mp4 links with mandatory attribution.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`orientation`	No
`size`	No
`locale`	No
`per_page`	No
`force_refresh`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`kind`	Yes
`creatorName`	Yes
`creatorUrl`	Yes
`pageUrl`	Yes
`previewUrl`	Yes
`mediaUrl`	Yes
`mediaMimeType`	Yes
`dimensions`	Yes
`durationSeconds`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal read-only, non-destructive, idempotent behavior. The description adds value by disclosing that results are HD-quality .mp4 links with mandatory attribution, which are not implied by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and key details. Every word earns its place with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, covering return values. The description adds helpful context on output format and attribution. Missing aspects like pagination and enum specifics are minor given overall clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description provides no individual parameter explanations. It only mentions 'optional filters' generically, failing to compensate for the missing schema descriptions of the 6 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for stock videos by query with optional filters. It mentions HD-quality .mp4 links and mandatory attribution, which distinguishes it from sibling tools like pexels_search_photos (photos) and pexels_get_details (details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for video searches via 'stock videos' and optional filters, but does not explicitly state when to use this tool over siblings. However, the tool name and context signals make the distinction clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesJun 3, 2026

Changedpexels_search_photos1 field changed

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "alt": {
+      "type": "string"
+    },
+    "avgColor": {
+      "type": "string"
+    },
+    "creatorName": {
+      "type": "string"
+    },
+    "creatorUrl": {
+      "type": "string"
+    },
+    "dimensions": {
+      "additionalProperties": false,
+      "properties": {
+        "height": {
+          "type": "number"
+        },
+        "width": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "type": "object"
+    },
+    "id": {
+      "type": "number"
+    },
+    "kind": {
+      "const": "photo",
+      "type": "string"
+    },
+    "mediaMimeType": {
+      "const": "image/jpeg",
+      "type": "string"
+    },
+    "mediaUrl": {
+      "type": "string"
+    },
+    "pageUrl": {
+      "type": "string"
+    },
+    "previewUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "creatorName",
+    "creatorUrl",
+    "pageUrl",
+    "previewUrl",
+    "mediaUrl",
+    "mediaMimeType",
+    "dimensions",
+    "avgColor",
+    "alt"
+  ],
+  "type": "object"
+}

Changedpexels_search_videos1 field changed

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "creatorName": {
+      "type": "string"
+    },
+    "creatorUrl": {
+      "type": "string"
+    },
+    "dimensions": {
+      "additionalProperties": false,
+      "properties": {
+        "height": {
+          "type": "number"
+        },
+        "width": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "type": "object"
+    },
+    "durationSeconds": {
+      "type": "number"
+    },
+    "id": {
+      "type": "number"
+    },
+    "kind": {
+      "const": "video",
+      "type": "string"
+    },
+    "mediaMimeType": {
+      "type": "string"
+    },
+    "mediaUrl": {
+      "type": "string"
+    },
+    "pageUrl": {
+      "type": "string"
+    },
+    "previewUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "creatorName",
+    "creatorUrl",
+    "pageUrl",
+    "previewUrl",
+    "mediaUrl",
+    "mediaMimeType",
+    "dimensions",
+    "durationSeconds"
+  ],
+  "type": "object"
+}

3 tool updatesv1.0.0May 3, 2026
- First observedpexels_get_details
- First observedpexels_search_photos
- First observedpexels_search_videos

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-06-03 04:01 across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: searching photos, searching videos, and getting details by ID. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'pexels_verb_noun' pattern using snake_case, making it predictable for an agent to infer functionality.

Tool Count4/5

Three tools is minimal but appropriate for a focused image/video search service. It covers the core workflow without unnecessary bloat.

Completeness4/5

The set covers search and retrieval of photos and videos, but lacks features like curated collections or trending content, which are minor omissions.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Organize with AIOAuth
ai.organizewith
Search photos/videos; manage collections, people and duplicates. Requires paid OwAI Cloud Access.
Image & Video Processing Entertainment & Media
1
Pexafy Stock Photos AOAuth
com.pexafy
Find free-to-use stock photos by words, by image or by similarity; every result names its licence.
Search Image & Video Processing AI & Machine Learning
52
Litescrape A
com.litescrape
Google, Bing, DuckDuckGo and Google Maps search results, free without an API key.
Search Browser Automation
101
joj-image-search C
com.jojapi
Image Search: Fast and Simple Image Search API. You can get 100+ search results in one query!.
Image & Video Processing Search
11

Related MCP Servers

MCP Image Extractor
Agent Orchestration Image & Video Processing Autonomous Agents
ifmelate
A
license
A
quality
C
maintenance
A Model Context Protocol server that extracts images from URLs or base64 data and converts them into a format suitable for LLM analysis, allowing AI models to process and understand visual content.
Updated 8 months ago (2026-02-28 14:28 UTC)
3
952 npm
21
MIT
Pexels MCP Server
Image & Video Processing Search
nikola-arman
A
license
Not graded
quality
D
maintenance
Enables searching and retrieving high-quality stock photos from Pexels with advanced filtering options including orientation, size, color, and localization support.
Updated a year ago (2025-08-21 02:53 UTC)
29 npm
ISC
Pexels MCP Server
Search Entertainment & Media
CaullenOmdahl
A
license
C
quality
F
maintenance
Enables AI models to search and retrieve photos, videos, and collections from Pexels via the Pexels API.
Updated a year ago (2025-06-01 15:13 UTC)
11
29 npm
9
ISC
Pexels MCP Server
Search Art & Culture
bighadj22
F
license
Not graded
quality
D
maintenance
Enables searching and displaying high-quality, royalty-free photos from Pexels directly in ChatGPT conversations via an interactive gallery widget.
Updated a year ago (2025-10-16 22:23 UTC)
2
-