Pexels MCP Server

Pexels API

Pexels provides a large library of high-quality stock photos and videos licensed under the Pexels License (personal and commercial use, no attribution required but appreciated).

Data Model

Photo Resource

src object sizes:

Video Resource

video_files element:

Collection Resource

Entity Relationships

• A Photo belongs to a Photographer (via photographer_id).
• A Video belongs to a User/Videographer (via user.id).
• A Collection contains mixed Photo and Video objects. Collection media items include an extra type field ("Photo" or "Video") to discriminate.
• Collections are read-only via API — create/edit on pexels.com, iOS, or Android app.

API Endpoints

Photos (base: /v1/)

Videos (base: /v1/videos/)

Collections (base: /v1/collections/)

Pagination

All list endpoints accept page (default 1) and per_page (default 15, max 80). Responses include page, per_page, total_results, and optional next_page/prev_page URL strings. The total_results for search endpoints is capped at a high number (e.g. 8000) even when more results exist.

Rate Limits

• Default: 200 requests/hour, 20,000 requests/month.
• Response headers: X-Ratelimit-Limit (monthly quota), X-Ratelimit-Remaining, X-Ratelimit-Reset (UNIX timestamp for monthly rollover).
• Rate limit headers are only returned on successful (2xx) responses, not on 429 errors.
• Higher limits available with proper attribution — contact api@pexels.com.

Search Tips & Gotchas

• Queries can be broad ("nature", "people") or specific ("group of people working").
• Color filter (photos only): Named colors (red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white) or hex codes (e.g. #ffffff).
• Locale affects search relevance for non-English queries. Supported: en-US, pt-BR, es-ES, ca-ES, de-DE, it-IT, fr-FR, sv-SE, id-ID, pl-PL, ja-JP, zh-TW, zh-CN, ko-KR, th-TH, nl-NL, hu-HU, vi-VN, cs-CZ, da-DK, fi-FI, uk-UA, el-GR, ro-RO, nb-NO, sk-SK, tr-TR, ru-RU.
• Size filter means different things: for photos, large = 24MP+, medium = 12MP+, small = 4MP+; for videos, large = 4K, medium = Full HD, small = HD.
• Video quality field may be null for newer video files — use width/height to determine actual resolution.
• Collection IDs are alphanumeric strings (not integers like photo/video IDs).
• The deprecated video base URL https://api.pexels.com/videos/ still works but should not be used — use /v1/videos/ instead.
• List responses are compact by default — search/list calls return slim rows (preview_url / download_link, duration, orientation, credit) unless full_detail=true. Single fetch by numeric photo or video ID returns the full upstream object.

Content creator workflow

Operational order for stock footage and b-roll:

1. Videos first — use video search for motion clips; photo search is for stills and thumbnails only.
2. Vertical short-form — orientation=portrait with max_duration around 15–30 for Reels, TikTok, and Shorts-style clips.
3. Keyword search — start broad ("cooking b-roll", "city night", "workspace timelapse") then narrow with duration and orientation filters. Pexels search is fuzzy; unrelated matches can appear — refine the query rather than assuming an empty catalog.
4. Curated packs — when keyword search feels noisy, list featured collections then open one with type=videos to browse editor-curated b-roll sets.
5. Pagination — default per_page is 15; raise to 25–40 only when the user needs more options on one page. Use page for the next batch.
6. Downloads — compact video rows include download_link (best HD MP4). Photo rows include download_url and preview_url. Link the Pexels page (url) and credit the creator when publishing.

Attribution

Best practice: link to the photo/video page on Pexels and credit the photographer/videographer (e.g. "Photo by John Doe on Pexels"). Use the url field from the response for attribution links.