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.

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

claude mcp add pexels \
  --env PEXELS_API_KEY=your_api_key \
  -- npx -y @hanoak/pexels-mcp-server

{
  "servers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

PEXELS_API_KEY=your_api_key npx -y @hanoak/pexels-mcp-server

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):

{
  "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 }
}

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

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 courtesy credit object.
• Videos → id, url, image, width/height, duration, user, video_files (trimmed to the top 5 by resolution in list results; complete on pexels_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_photo	subject (required), orientation?	Search for one photo and present it with a courtesy credit.
  photo_gallery	theme (required), count?, orientation?, color?	Build a themed set of photos (up to 10), each with a courtesy credit.
  find_video	subject (required), orientation?	Search for one video and present it with a courtesy credit.
  collection_tour	theme (required), count?	Find a matching featured collection and walk through its media.
  media_brief	theme (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:

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 Authorization header (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 env block.
• Node too old — this server requires Node 20+. Check node --version.
• Stale npx version — force the latest with npx -y @hanoak/pexels-mcp-server@latest, or clear the cache via npx 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 the rate_limit.resetEpoch in 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_collections returns 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

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.