# pexels-mcp-pro

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Pexels API](https://www.pexels.com/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 `#id`s 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](https://www.pexels.com/api/).

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

### Claude Code

```bash
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`)

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

```bash
npm run inspect
```

This opens the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) against the built server.

## License

MIT for this server. Media from Pexels is covered by the [Pexels license](https://www.pexels.com/license/): free to use, attribution appreciated but not required. `get_attribution` generates the credit line.