pexels-mcp-pro

A Model Context Protocol server for the Pexels API, built for fast, low-token stock media selection in Claude and other MCP clients.

Most Pexels MCP servers return raw JSON and leave the model to guess from alt text whether a photo fits. This one is designed around how an agent actually picks stock media: look at the candidates, judge, download the winner.

What it does differently

Inline visual previews. Search results include small thumbnails as images in the tool response, so the model sees every candidate and judges fit immediately. A thumbnail costs about 75 tokens of vision input; a wrong download costs far more.

Video storyboards. video_storyboard returns a clip's poster plus frames sampled evenly across its runtime. An agent can check the motion and framing of a 30-second video for a few hundred tokens instead of downloading 50 MB to find out it pans the wrong way.

Compact results. One line per item: #id 4000x6000 portrait | Photographer | "alt text" | #avgcolor. Search results contain no URLs. The #id drives previews, downloads, and attribution, and get_media returns full URLs on the rare occasion you need them.

Careful with quota. API responses are cached, and every media object seen in a search is remembered for the session, so previews, storyboards, downloads, and attribution for seen items cost no further API calls. Thumbnail and file fetches never count against the Pexels rate limit. api_status reports remaining quota and reset time.

Batch operations. batch_search runs up to 6 queries in parallel in one call and dedupes results across them, which suits multi-scene videos and article layouts. download_media streams up to 20 files to disk with selectable quality and returns paths with ready-to-paste attribution.

Tools

Tool	What it does
search_photos	Search photos: compact lines plus inline thumbnails, with orientation/size/color/locale filters
search_videos	Search videos: compact lines plus inline posters, with duration filters
batch_search	Up to 6 queries in parallel, one call, deduped
preview_photos	Re-inspect specific #ids at a larger size before deciding
video_storyboard	Poster plus sampled in-clip frames as inline images
curated_photos	Pexels' hand-curated feed
popular_videos	Popular videos with minimum-resolution and duration constraints
featured_collections	Browse featured collections
collection_media	Media inside a collection
get_media	Full metadata and all URLs for one item
download_media	Stream up to 20 photos/videos to disk, returns paths and attribution
get_attribution	Attribution lines in plain text, Markdown, or HTML
api_status	Remaining quota and session cache stats

A typical session

search_photos "cozy cabin interior warm light"
  → 6 result lines + 6 thumbnails; the model looks and picks #2932401

download_media [{"type": "photo", "id": 2932401}]
  → ✓ pexels-photo-2932401.jpg (4.1 MB) — Photo by Jane Doe — https://www.pexels.com/photo/...

Setup

Requires Node 18+ and a free Pexels API key.

git clone https://github.com/fkilter/pexels-mcp-pro.git
cd pexels-mcp-pro
npm install && npm run build

Claude Code

claude mcp add pexels --env PEXELS_API_KEY=your_key -- node /path/to/pexels-mcp-pro/dist/index.js

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/path/to/pexels-mcp-pro/dist/index.js"],
      "env": {
        "PEXELS_API_KEY": "your_key"
      }
    }
  }
}

You can also put the key in a .env file next to the package (see .env.example); .env is gitignored. The optional PEXELS_DOWNLOAD_DIR variable sets the default target directory for download_media.

Debugging

npm run inspect

This opens the MCP Inspector against the built server.

License

MIT for this server. Media from Pexels is covered by the Pexels license: free to use, attribution appreciated but not required. get_attribution generates the credit line.