pexels-mcp-server
About
Production-ready Model Context Protocol (MCP) server for the Pexels API — search and browse photos and videos, with license-aware usage guidance. Unofficial; not affiliated with or endorsed by Pexels.
Details
- Author
- hanoak
- Categories
- Search, Knowledge Base, Other
Jump to
Setup
Install pexels-mcp-server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/hanoak/pexels-mcp-server
Follow the installation instructions in the repository README, then restart your MCP client.
A production-readyModel Context Protocol(MCP) server for thePexels 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, coveringevery endpoint the Pexels API documents.
[!IMPORTANT]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 thePexels License.
- Features
- Quick start
- Example interaction
- Configuration
- Tools
- Tool reference
- Output shape
- Resources & prompts
- 9 toolscovering 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 courtesycredit(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-sizedsrcURLs (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 MCPisErrorresults 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 vianpx, no telemetry.
Create a free account atpexels.com/apiand you'll receive an API key instantly — no app review, no approval wait.
Claude Desktop— editclaude_desktop_config.json:
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%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. SeeConfigurationfor every supported variable.
claude mcp add pexels \ --env PEXELS_API_KEY=your_api_key \ -- npx -y @hanoak/pexels-mcp-server
Cursor—~/.cursor/mcp.json(global) or.cursor/mcp.json(per-project): use the exact samemcpServersblock as Claude Desktop above.
Windsurf—~/.codeium/windsurf/mcp_config.json: samemcpServersblock as Claude Desktop above.
VS Code—.vscode/mcp.json(note the top-level key isservers, notmcpServers):
{ "servers": { "pexels": { "command": "npx", "args": ["-y", "@hanoak/pexels-mcp-server"], "env": { "PEXELS_API_KEY": "your_api_key" } } } }
Any other MCP client— run the server overstdiowith:
PEXELS_API_KEY=your_api_key npx -y @hanoak/pexels-mcp-server
Point your client's stdio transport atcommand: npx,args: ["-y", "@hanoak/pexels-mcp-server"], and pass the key viaenv.
"Find me a photo of mountains on Pexels."
A typical flow: the model callspexels_search_photos, picks a result, and presents the image with its courtesy credit.
You:Find a landscape photo of a foggy pine forest.
Assistant:(callspexels_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 arate_limitobject (limit,remaining,resetEpoch) read from the Pexels response headers. List/search tools wrap results inphotos/videos/collections/mediaarrays with pagination fields (total_results,page,per_page,has_next_page).
Configuration is entirely via environment variables — no config files, no flags for secrets.
CLI flags:--versionand--helpare supported (e.g.npx @hanoak/pexels-mcp-server --version).
All tools are namespacedpexels_and every one isread-only(readOnlyHint: true) — Pexels' API has no write endpoints, so a client can safely auto-approve the entire server.per_pageis clamped to a max of80(Pexels' own documented max), andpageis 1-based.
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 arate_limit(limit,remaining,resetEpoch); lists/searches add pagination fields (total_results,page,per_page,has_next_page).
-
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:
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."
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 courtesycreditobject — 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 fullPexels Licenseand the server'spexels://guides/usageresource. Each user operates under their own Pexels API Terms.
Pexels enforces a single tier for every API key:
The server readsX-Ratelimit-Limit/X-Ratelimit-Remaining/X-Ratelimit-Resetand returns them asrate_limiton every result. Pexels returns a standard429when the budget is exhausted (unlike some APIs that overload403for this) — but the rate-limit headers are absent on the429response 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. Transient429/5xx/network errorsare*retried with backoff.
Photo/video alt text, photographer names, and collection titles/descriptions come from Pexels contributors — treat them asuntrusted, 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.
- No telemetry.This server collects nothing and phones home to no one. It contacts onlyapi.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 rawAuthorizationheader (never in a URL query string), andredacted from all error output and logsso it can't leak into pasted bug reports.
- To report a vulnerability, seeSECURITY.md.
- "Set PEXELS_API_KEY…" on startup— the key env var is missing or blank; add it to your client config'senvblock.
- Node too old— this server requiresNode 20+. Checknode --version.
- Stalenpxversion— 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 yourPexels 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 theFAQ.
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 doespexels_list_my_collectionscome 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. Seethe client setup sectionfor Claude Code, Cursor, VS Code, Windsurf, and generic stdio.
- Node.js >= 20(Node 18 is end-of-life).
- A Pexels API key.
Changes are tracked inCHANGELOG.md; the project followsSemantic Versioning.
Contributions are welcome — seeCONTRIBUTING.mdand ourCode of Conduct. It covers local setup, the test suite, testing tools by hand with theMCP Inspector, and the versioning/deprecation policy. To report a vulnerability, seeSECURITY.md.
Maintained byHanoak S. The fastest way to get help or propose a feature is toopen an issue— it's public, searchable, and helps the whole community.
If this project helps you, a ⭐ onGitHubis appreciated — it aids discoverability for others looking for a Pexels MCP server.
MIT© Hanoak S. Not affiliated with Pexels.
Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.
Fetch, convert, and search AWS documentation pages, with recommendations for related content.
Search campgrounds around the world on campertunity, check availability, and provide booking links.
The Ferryhopper MCP Server exposes ferry routes, schedules and booking redirects so an AI assistant can discover connections across Europe and the Mediterranean and send users to Ferryhopper to complete bookings.
All-in-One SEO & Web Intelligence Toolkit API from FetchSERP.
MCP server that provides read-only access to HyperKitty, the web-based email archive component of Mailman 3.
At Sunrise Apps, we believe AI agents should be limitless, especially when it comes to visual data. We created ImageSorcery to bridge the critical gap in AI's ability to interact with and manipulate images directly, all while upholding the highest standards of privacy and security.
Just Domain is the domain registrar for businesses built with AI. Its remote MCP server checks availability and returns first-year and renewal pricing, plus a link to register on justdomain.ai, with DNS and WHOIS privacy in the same place. No account, no API key, read only. Endpoint: https://mcp.justdomain.ai/
Research tools, including a Sqlite-backed document stash
Semantic search over 9 free-license stock photo sources. Hosted remote server with OAuth — no API key to paste.
SerpApi MCP Server for Google and other search engine results
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.




