jeanpfs/stock-images-mcp

An MCP (Model Context Protocol) server for searching and downloading stock images from Pexels, Unsplash, and Pixabay.
## Features
searchimages: search one or all configured providers; partial failures are reported per provider
downloadimage: download an image safely into a local folder
## Setup
### Get API keys (at least one required)
| Provider | Env var | Get a key |
| Pexels | PEXELSAPIKEY | https://www.pexels.com/api/ |
| Unsplash | UNSPLASHAPIKEY | https://unsplash.com/developers |
| Pixabay | PIXABAYAPIKEY | https://pixabay.com/api/docs/ |
Optional: STOCKIMAGESDOWNLOADDIR — where downloadimage writes files (default ./downloads).
### Claude Code / Cursor / Claude Desktop
Add to your MCP config (~/.claude/mcp.json, ~/.cursor/mcp.json, or claudedesktopconfig.json):
json
"mcpServers": {
"stock-images": {
"command": "npx",
"args": ["-y", "stock-images-mcp"],
"env": {
"PEXELSAPIKEY": "your-key-here",
"UNSPLASHAPIKEY": "your-key-here",
"PIXABAYAPIKEY": "your-key-here"
Requires Node.js 22+.
### Docker
bash
docker build -t stock-images-mcp .
docker run -i --rm -e PEXELSAPIKEY=xxx -v "$PWD/downloads:/downloads" stock-images-mcp
### From source
bash
git clone https://github.com/jeanpfs/stock-images-mcp.git
cd stock-images-mcp
npm ci && npm run build
PEXELSAPIKEY=xxx node dist/index.js
## Tools
### searchimages
Search for stock images across configured providers.
Parameters:
query (required): search term
provider: "pexels", "unsplash", "pixabay", or "all" (default: "all")
count: results per provider (default 5, max 20)
orientation: "landscape", "portrait", or "square"
Each result has id, provider, url, thumbnail, description, author, authorUrl, downloadUrl, width, height. Pass downloadUrl to downloadimage.
### downloadimage
Download an image into the download directory.
Parameters:
url (required): https image URL on pexels.com, unsplash.com or pixabay.com (use downloadUrl from searchimages)
filename: output name — letters, digits, , -, . only; the extension is added from the content-type if missing (auto-generated if omitted)
folder: subfolder inside the download directory
Behavior and limits:
Download directory is ./downloads, or STOCKIMAGESDOWNLOADDIR if set. Paths that escape it (including via symlinks) are rejected.
Only image/ responses are saved; max 50 MiB; 30 s timeout; redirects are followed only to allowed hosts.
Existing files are never overwritten.
Unsplash downloads require UNSPLASHAPIKEY: the tool calls Unsplash's download endpoint, as their API guidelines require.