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.

Related MCP server: mcp-media-engine

Tools

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.