pexels-mcp

MCP + CLI toolkit to search and download free Pexels stock images/videos.

• Zero third-party dependencies — pure Python standard library (urllib). Install, run, done.
• No API key, no quota — talks to Pexels' own web front-end API v3 (the public secret-key constant Pexels hardcodes in its JS).
• Built-in relevance gate — Pexels returns something for any query (even zzzqqqxxx_not_exist_9999). This tool validates every candidate against title/tags and drops 0-hit junk, so you never get unrelated footage.
• Right resolution tier, automatically — picks the video_files tier closest to your target (default 1080×1920 portrait) and refuses to upscale postage-stamp clips.
• Chinese query rejected — the English site can't search Chinese meaningfully. Translate to concrete English words (office meeting > work).

Works as an MCP server (5 tools) or a plain CLI.

Quick start

pip install pexels-mcp          # or: uvx pexels-mcp@latest

As an MCP server

{
  "mcpServers": {
    "pexels": {
      "command": "uvx",
      "args": ["pexels-mcp@latest"],
      "env": { "PEXELS_OUT_DIR": "/tmp/pexels_download" }
    }
  }
}

Any MCP client (Claude Desktop, CowAgent, …) sees 5 tools:

PEXELS_OUT_DIR sets the download folder (default: OS temp dir).

As a CLI

pexels-cli search "elderly woman face" --kind video --n 5
pexels-cli search "office meeting" --json
pexels-cli get "hands holding cash" -o ./out --n 2
pexels-cli health
pexels-cli info

All subcommands support --json for machine-readable output.

Why it's reliable

• No fake hits: Pexels fabricates total_results even for nonsense queries. We split your query into content tokens (with a stop-word list — not must not match do not lean), and require ≥1 token to actually appear in the item's title/tags/slug. A test with zzzqqqxxx_not_exist_9999 returns 0 hits.
• No decompression trap: we request Accept-Encoding: identity (avoid brotli unless you have it) and fall back to gunzip.
• Throttle-safe: measured 100 sequential + 8-way parallel direct downloads at 100% success with no Cloudflare intervention.
• Bomb fuse: downloads stream with size cap, and a text/html response is rejected as a Cloudflare block page masquerading as HTTP 200.

Notes

• This package is just "give me a keyword → get good direct-link stock media". It does not assemble videos — pair it with an assembler MCP (e.g. video-assembler-mcp) for the full pipeline.
• The endpoint is Pexels' own public web API and could change at any time. It's a third-party behavior, out of our control; pexels_health exists precisely to catch that the day it happens.

License

MIT