Pexels MCP Server

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.

[!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 the Pexels License.

Table of contents

• Features
• Quick start
• Example interaction
• Configuration
• Tools
• Tool reference
• Output shape
• Resources & prompts
• Example prompts
• License & compliance
• Rate limits
• Handling of Pexels text
• Privacy & security
• Troubleshooting
• FAQ
• Requirements
• Compatibility
• Roadmap
• Contributing
• Contact & community
• License

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 src URLs (original/large2x/large/medium/small/portrait/landscape/tiny); each video returns its video_files renditions (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 isError results the model can recover from, plus retries/backoff, timeouts, and rate-limit-aware quota short-circuiting (Pexels omits its rate-limit headers on a 429, 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](https://www.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.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. See Configuration for every supported variable.

Other clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)

Claude Code (CLI):

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 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-server

Point 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_photos with query: "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):

Example tool output

{

"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 Jane Doe on Pexels " } }, "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.

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.

Tool reference

Photos

Videos

| pexels_popular_videos | `min_widt