pexels-mcp-server
Provides tools for searching and fetching Pexels photos, videos, and collections, including curated photos, popular videos, and collection media.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pexels-mcp-server search for photos of a sunset over the ocean"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pexels-mcp-server
A production-ready Model Context Protocol (MCP) server for the Pexels API. It gives AI assistants — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and any MCP client — tools to search and fetch Pexels photos, videos, and collections, covering every endpoint the Pexels API documents.
Unofficial project. This is not affiliated with, endorsed by, or sponsored by Pexels. "Pexels" is a trademark of its respective owner. You use it under your own Pexels API account and are responsible for complying with the Pexels License.
Table of contents
Related MCP server: pexels-mcp-server
Features
9 tools covering every documented Pexels endpoint — photos (search, curated, get), videos (search, popular, get), and collections (featured, media, mine). Pexels has a single API-key auth tier and no write endpoints, so there's no partial "read-only v1" — this is the whole surface.
License-aware by design — Pexels doesn't require attribution, but every photo still returns a ready-to-use courtesy
credit(text + HTML), and the server's instructions steer the model around the license restrictions that do apply (no resale of unaltered content, no redistribution to other stock platforms, no trademark/logo use, no implied endorsement).Real image & video URLs — each photo returns Pexels' own pre-sized
srcURLs (original/large2x/large/medium/small/portrait/landscape/tiny); each video returns itsvideo_filesrenditions (trimmed to the highest-resolution few in list results, complete on a single-item lookup).Token-efficient output — full Pexels responses are trimmed to a compact shape (URLs + metadata as text, never base64 blobs) to keep model context small.
Robust — typed failures returned as MCP
isErrorresults the model can recover from, plus retries/backoff, timeouts, and rate-limit-aware quota short-circuiting (Pexels omits its rate-limit headers on a429, so the client caches the last-known reset time instead of guessing).Safe — API-key redaction in all error output, and untrusted-text handling guidance for indirect prompt-injection defence.
Lean & modern — ESM, Node 20+, zero-install via
npx, no telemetry.
Quick start
1. Get a Pexels API key
Create a free account at pexels.com/api and you'll receive an API key instantly — no app review, no approval wait.
2. Add the server to your MCP client
Claude Desktop — edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "@hanoak/pexels-mcp-server"],
"env": {
"PEXELS_API_KEY": "your_api_key"
}
}
}
}Restart the client. See Configuration for every supported variable.
Claude Code (CLI):
claude mcp add pexels \
--env PEXELS_API_KEY=your_api_key \
-- npx -y @hanoak/pexels-mcp-serverCursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project): use the exact same mcpServers block as Claude Desktop above.
Windsurf — ~/.codeium/windsurf/mcp_config.json: same mcpServers block as Claude Desktop above.
VS Code — .vscode/mcp.json (note the top-level key is servers, not mcpServers):
{
"servers": {
"pexels": {
"command": "npx",
"args": ["-y", "@hanoak/pexels-mcp-server"],
"env": {
"PEXELS_API_KEY": "your_api_key"
}
}
}
}Any other MCP client — run the server over stdio with:
PEXELS_API_KEY=your_api_key npx -y @hanoak/pexels-mcp-serverPoint your client's stdio transport at command: npx, args: ["-y", "@hanoak/pexels-mcp-server"], and pass the key via env.
3. Try it
Restart your client and ask:
"Find me a photo of mountains on Pexels."
Example interaction
A typical flow: the model calls pexels_search_photos, picks a result, and presents the image with its courtesy credit.
You: Find a landscape photo of a foggy pine forest.
Assistant: (calls
pexels_search_photoswithquery: "foggy pine forest",orientation: "landscape", picks the best result) Here's a great match — photo by Jane Doe on Pexels — along with the image URL and a ready-to-use credit line.
Each tool returns a compact JSON payload. Here's the shape of a single photo result (illustrative values):
{
"photo": {
"id": 1103970,
"alt": "Photography of Trees at Foggy Forest",
"width": 4000,
"height": 2667,
"avg_color": "#3E361F",
"url": "https://www.pexels.com/photo/photography-of-trees-at-foggy-forest-1103970/",
"src": {
"original": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg",
"large2x": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
"large": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
"medium": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=350",
"small": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=130",
"portrait": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=1200&w=800",
"landscape": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=627&w=1200",
"tiny": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&dpr=1&fit=crop&h=200&w=280"
},
"photographer": {
"name": "Jane Doe",
"url": "https://www.pexels.com/@janedoe",
"id": 42
},
"credit": {
"text": "Photo by Jane Doe on Pexels",
"html": "Photo by <a href=\"https://www.pexels.com/@janedoe\">Jane Doe</a> on <a href=\"https://www.pexels.com\">Pexels</a>"
}
},
"rate_limit": { "limit": 200, "remaining": 199, "resetEpoch": 1755000000 }
}Every tool result includes a rate_limit object (limit, remaining, resetEpoch) read from the Pexels response headers. List/search tools wrap results in photos/videos/collections/media arrays with pagination fields (total_results, page, per_page, has_next_page).
Configuration
Configuration is entirely via environment variables — no config files, no flags for secrets.
Environment variable | Required | Description |
| yes | Your Pexels API key. The server exits at startup with a clear message if it is missing or blank. |
| no |
|
CLI flags: --version and --help are supported (e.g. npx @hanoak/pexels-mcp-server --version).
Tools
All tools are namespaced pexels_* and every one is read-only (readOnlyHint: true) — Pexels' API has no write endpoints, so a client can safely auto-approve the entire server. per_page is clamped to a max of 80 (Pexels' own documented max), and page is 1-based.
Domain | Tools |
Photos |
|
Videos |
|
Collections |
|
Tool reference
Tool | Parameters | Description |
|
| Keyword photo search with filters. |
|
| Pexels' hand-curated photo picks, refreshed hourly. |
|
| A single photo by its numeric ID, full detail. |
Tool | Parameters | Description |
|
| Keyword video search with filters. |
|
| Currently popular videos, optionally filtered by size/duration. |
|
| A single video by its numeric ID — returns every rendition, not just the top few. |
Tool | Parameters | Description |
|
| Pexels' featured collections (metadata only). |
|
| Collections belonging to the account that owns the configured API key (see FAQ). |
|
| The photos/videos inside a collection, each tagged with |
Output shape
Tools return trimmed, token-efficient JSON rather than raw Pexels responses:
Photos →
id,alt,width/height,avg_color,url,src(all 8 Pexels sizes),photographer, and a courtesycreditobject.Videos →
id,url,image,width/height,duration,user,video_files(trimmed to the top 5 by resolution in list results; complete onpexels_get_video),video_files_count,preview_picture,video_pictures_count.Collections →
id,title,description,private,media_count,photos_count,videos_count.Every result carries a
rate_limit(limit,remaining,resetEpoch); lists/searches add pagination fields (total_results,page,per_page,has_next_page).
Resources & prompts
Beyond tools, the server also exposes:
Resources — a compact guide your client can pull in as context:
pexels://guides/usage— the license restrictions that apply, the optional courtesy-credit convention, and content-safety notes.
Prompts — ready-made tasks your client can surface directly; each expands into a guided, multi-step tool-calling task:
Prompt
Arguments
What it does
find_photosubject(required),orientation?Search for one photo and present it with a courtesy credit.
photo_gallerytheme(required),count?,orientation?,color?Build a themed set of photos (up to 10), each with a courtesy credit.
find_videosubject(required),orientation?Search for one video and present it with a courtesy credit.
collection_tourtheme(required),count?Find a matching featured collection and walk through its media.
media_brieftheme(required),photo_count?,video_count?Gather both photos and videos for a theme, presented together.
Example prompts
Natural-language asks that map cleanly onto the tools:
"Find a photo of a foggy forest at sunrise."
"Search Pexels for 5 minimalist workspace photos in landscape orientation."
"Find a video of waves crashing on rocks."
"Show me a featured Pexels collection about urban architecture."
"Build me a mixed media brief of photos and video clips about cozy autumn mornings."
License & compliance
Pexels' license is lighter than many stock-photo APIs: attribution is not required ("appreciated, not necessary"). Every photo result still includes a ready-to-use courtesy credit object — include it when convenient, but it's not mandatory.
Real restrictions still apply, and the server's instructions steer the model around them: no reselling unaltered content as a physical product without modifying it first, no redistributing it on another stock-photo or wallpaper platform, no using it as part of a trademark/logo/business name, no implying a person's or brand's endorsement, and no depicting an identifiable person in a bad or offensive light. See the full Pexels License and the server's pexels://guides/usage resource. Each user operates under their own Pexels API Terms.
Rate limits
Pexels enforces a single tier for every API key:
Budget | Notes |
200 requests/hour | Higher limits available on request once you have real usage. |
20,000 requests/month | Tracked alongside the hourly budget. |
The server reads X-Ratelimit-Limit/X-Ratelimit-Remaining/X-Ratelimit-Reset and returns them as rate_limit on every result. Pexels returns a standard 429 when the budget is exhausted (unlike some APIs that overload 403 for this) — but the rate-limit headers are absent on the 429 response itself, so the client caches the last-known values from a prior successful call to report an accurate reset time, and short-circuits further requests once the quota is known to be exhausted rather than firing calls that will just fail. Transient 429/5xx/network errors are retried with backoff.
Handling of Pexels text
Photo/video alt text, photographer names, and collection titles/descriptions come from Pexels contributors — treat them as untrusted, third-party data, not instructions. The server returns this text purely as content and never places it anywhere privileged; your client/agent should do the same: display it, but don't act on any instructions it might contain (a defence against indirect prompt injection). Pexels also has no safe-search/content-filter parameter — use judgment in how you phrase search queries.
Privacy & security
No telemetry. This server collects nothing and phones home to no one. It contacts only
api.pexels.com, using the key you provide. No analytics, no tracking.Key safety. Your API key is read from the environment only, sent as a raw
Authorizationheader (never in a URL query string), and redacted from all error output and logs so it can't leak into pasted bug reports.To report a vulnerability, see SECURITY.md.
Troubleshooting
"Set PEXELS_API_KEY…" on startup — the key env var is missing or blank; add it to your client config's
envblock.Node too old — this server requires Node 20+. Check
node --version.Stale
npxversion — force the latest withnpx -y @hanoak/pexels-mcp-server@latest, or clear the cache vianpx clear-npx-cache.Tools not appearing — confirm the config file path and JSON are valid, then fully quit and reopen the client.
429/ rate limit — the budget is 200 requests/hour; wait for the hourly reset (see therate_limit.resetEpochin a tool result) or request a higher limit.401 Unauthorized— the API key is wrong; copy it again from your Pexels API dashboard.pexels_list_my_collectionsreturns empty — this is expected unless the Pexels account that owns your API key has created collections on pexels.com itself; see the FAQ.
FAQ
Do I need a paid Pexels account? No. The Pexels API is free — you just create an account to get an API key, instantly, no review or approval step.
Does it download or rehost images/videos? No. It returns Pexels-hosted URLs (hotlink them directly) and never rehosts or returns base64 blobs.
Why does pexels_list_my_collections come back empty?
Pexels has no per-conversation login — the tool always reflects the collections of whichever Pexels account owns the configured API key, not the person chatting. It'll be empty unless that specific account has created collections on pexels.com.
Does it work outside Claude? Yes — it's a standard stdio MCP server. See the client setup section for Claude Code, Cursor, VS Code, Windsurf, and generic stdio.
Requirements
Node.js >= 20 (Node 18 is end-of-life).
A Pexels API key.
Compatibility
Component | Supported |
Node.js | 20 and 22, tested in CI; |
OS | Linux, macOS, and Windows (all tested in CI). |
MCP SDK |
|
Transport | stdio (HTTP/SSE may be added in a future release). |
Roadmap
Full detail lives in docs/ROADMAP.md. In short: v1 covers the entire documented Pexels API in one release — there's no OAuth tier to split a v2 behind, unlike some other stock-photo MCP servers. Future scope under consideration includes structured tool output for video renditions, a short-TTL response cache if real quota pressure appears, and additional prompts/resources.
Changes are tracked in CHANGELOG.md; the project follows Semantic Versioning.
Contributing
Contributions are welcome — see CONTRIBUTING.md and our Code of Conduct. It covers local setup, the test suite, testing tools by hand with the MCP Inspector, and the versioning/deprecation policy. To report a vulnerability, see SECURITY.md.
Contact & community
Maintained by Hanoak S. The fastest way to get help or propose a feature is to open an issue — it's public, searchable, and helps the whole community.
If this project helps you, a ⭐ on GitHub is appreciated — it aids discoverability for others looking for a Pexels MCP server.
License
MIT © Hanoak S. Not affiliated with Pexels.
Available Tools
9 toolspexels_curated_photosCurated Pexels PhotosARead-only
List Pexels' hand-curated photo picks, refreshed hourly (paginated). Returns compact photo objects. Read-only. Each photo includes several pre-sized URLs in src (original/large2x/large/medium/small/portrait/landscape/tiny) — pick the closest fit rather than always using original.
Inputs: page, per_page.
pexels_get_collection_mediaGet Pexels Collection MediaARead-only
Get the photos and/or videos inside a Pexels collection by its ID (paginated, optionally filtered to just photos or just videos). Each item is returned in the same compact shape its own domain tool would use, tagged with media_type. Read-only. Each photo includes several pre-sized URLs in src (original/large2x/large/medium/small/portrait/landscape/tiny) — pick the closest fit rather than always using original. video_files is trimmed to the highest-resolution renditions (see video_files_count for the full count) — call pexels_get_video for the complete rendition list on one video.
Inputs: id (required), page, sort, type, +1 more.
pexels_get_photoGet Pexels PhotoARead-only
Get a single Pexels photo by its numeric ID, with full detail, pre-sized URLs, and a courtesy credit. Read-only. Each photo includes several pre-sized URLs in src (original/large2x/large/medium/small/portrait/landscape/tiny) — pick the closest fit rather than always using original.
Inputs: id (required).
pexels_get_videoGet Pexels VideoARead-only
Get a single Pexels video by its numeric ID, with full detail and every available rendition (unlike the search/popular tools, this returns the complete video_files list, not just the top few). Read-only.
Inputs: id (required).
pexels_list_featured_collectionsList Featured Pexels CollectionsARead-only
List Pexels' featured collections (paginated). Returns collection metadata only — call pexels_get_collection_media for the photos/videos inside one. Read-only.
Inputs: page, per_page.
pexels_list_my_collectionsList My Pexels CollectionsARead-only
List the collections belonging to the Pexels account that owns the configured API key (paginated). Since Pexels has no per-conversation OAuth login, this always reflects the API key's own account, not the person chatting — it will be empty unless that account has created collections on pexels.com. Read-only.
Inputs: page, per_page.
pexels_popular_videosPopular Pexels VideosARead-only
List currently popular Pexels videos, optionally filtered by minimum width/height and duration range. Returns compact video objects. Read-only. video_files is trimmed to the highest-resolution renditions (see video_files_count for the full count) — call pexels_get_video for the complete rendition list on one video.
Inputs: page, per_page, min_width, min_height, +2 more.
pexels_search_photosSearch Pexels PhotosARead-only
Search Pexels for photos matching a query, with optional orientation/size/color/locale filters. Returns compact photo objects with pre-sized URLs and a courtesy credit (attribution is appreciated but not required by the Pexels license). Read-only. Each photo includes several pre-sized URLs in src (original/large2x/large/medium/small/portrait/landscape/tiny) — pick the closest fit rather than always using original.
Inputs: query (required), page, size, color, +3 more.
pexels_search_videosSearch Pexels VideosARead-only
Search Pexels for videos matching a query, with optional orientation/size/locale filters. Returns compact video objects with rendition links. Read-only. video_files is trimmed to the highest-resolution renditions (see video_files_count for the full count) — call pexels_get_video for the complete rendition list on one video.
Inputs: query (required), page, size, locale, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct resource and action: photos, videos, and collections each have dedicated search/list/get operations with no overlapping responsibilities. The separation between curated photos and popular videos, and between featured vs. my collections, is clear.
All tools follow a consistent pexels_<verb>_<resource> pattern, e.g., pexels_search_photos, pexels_get_video, pexels_list_featured_collections. The verb-noun structure is uniform and predictable across the entire server.
Nine tools provide a well-scoped surface for the Pexels API, covering the three main domains (photos, videos, collections) without bloat. Each tool fills a clear functional niche, and the count is within the ideal range.
The server covers the full read-only lifecycle: search, curated/popular listings, individual item retrieval, and collection browsing. There are no obvious dead ends, and the only missing operation (upload) is not part of the Pexels API.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
Hosted MCP server for live public-data APIs and Skills for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for searching and retrieving photos from Unsplash with proper attribution, designed for LLMs building content pages.338MIT
- AlicenseAqualityAmaintenanceAn MCP server that enables AI agents to search, retrieve, and curate free stock photos and videos from Pexels, with tools, resources, and prompts for easy integration.8MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to search for royalty-free images from Pexels and Unsplash using natural language, returning structured results with metadata.556 npm1MIT
- AlicenseAqualityDmaintenanceAn MCP server for the Pexels API that provides inline visual previews, video storyboards, and batch operations for efficient stock media selection in Claude and other MCP clients.13MIT