Pexels

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

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