stock-images-mcp
This server provides MCP tools to search stock images and download them locally.
search_images: Search images with a required
query; optionally filter byprovider(pexels,unsplash,pixabay,all; currently available:pexels),count(1–20, default 5), andorientation(landscape,portrait,square). Returns metadata includingdownloadUrl.download_image: Download an allowed
httpsimage URL from Pexels, Unsplash, or Pixabay into a download directory; optionally specifyfilenameandfolder; refuses to overwrite existing files.Safety/limits: Saves only
image/*files up to 50 MiB, uses a 30s timeout, restricts redirects, prevents path traversal, and requiresUNSPLASH_API_KEYfor Unsplash downloads.
Allows for searching and downloading stock images from the Pexels platform, with support for filtering by orientation and count.
Enables searching and downloading stock images from Pixabay's collection of stock media.
Provides tools for searching and downloading high-quality stock images from the Unsplash library.
Stock Images MCP
An MCP (Model Context Protocol) server for searching and downloading stock images from Pexels, Unsplash, and Pixabay.
Features
search_images: search one or all configured providers; partial failures are reported per provider
download_image: download an image safely into a local folder
Related MCP server: Pexels MCP Server
Setup
Get API keys (at least one required)
Provider | Env var | Get a key |
Pexels |
| |
Unsplash |
| |
Pixabay |
|
Optional: STOCK_IMAGES_DOWNLOAD_DIR — where download_image writes files (default ./downloads).
Claude Code / Cursor / Claude Desktop
Add to your MCP config (~/.claude/mcp.json, ~/.cursor/mcp.json, or claude_desktop_config.json):
{
"mcpServers": {
"stock-images": {
"command": "npx",
"args": ["-y", "stock-images-mcp"],
"env": {
"PEXELS_API_KEY": "your-key-here",
"UNSPLASH_API_KEY": "your-key-here",
"PIXABAY_API_KEY": "your-key-here"
}
}
}
}Requires Node.js 22+.
Docker
docker build -t stock-images-mcp .
docker run -i --rm -e PEXELS_API_KEY=xxx -v "$PWD/downloads:/downloads" stock-images-mcpFrom source
git clone https://github.com/jeanpfs/stock-images-mcp.git
cd stock-images-mcp
npm ci && npm run build
PEXELS_API_KEY=xxx node dist/index.jsTools
search_images
Search for stock images across configured providers.
Parameters:
query(required): search termprovider:"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 download_image.
download_image
Download an image into the download directory.
Parameters:
url(required):httpsimage URL onpexels.com,unsplash.comorpixabay.com(usedownloadUrlfromsearch_images)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, orSTOCK_IMAGES_DOWNLOAD_DIRif 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
UNSPLASH_API_KEY: the tool calls Unsplash's download endpoint, as their API guidelines require.
Errors
Failures return isError: true. search_images also returns a per-provider errors list when some providers fail but others succeed. Provider requests time out after 10 s and are retried on network errors, 429 and 502/503/504.
Attribution and licensing
Images stay under each provider's license. Credit the photographer where the provider requires it (author and authorUrl are returned for that purpose) and review the terms: Pexels, Unsplash, Pixabay.
Development
npm ci
npm run lint && npm run format:check && npm run typecheck && npm testSee CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md (report vulnerabilities privately, not in public issues).
License
MIT
Available Tools
2 toolsdownload_imageA
Download a stock image (https URL on pexels.com, unsplash.com or pixabay.com) into the download directory. Refuses to overwrite existing files.
Inputs: url (required), folder, filename.
search_imagesC
Search stock images across providers. Available providers: pexels
Inputs: query (required), count, provider, orientation.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: search_images finds images and download_image retrieves a specific one to disk. There is no plausible way to confuse them, and their boundaries are crisp.
Both follow the same verb_noun snake_case pattern (search_images, download_image). Fully predictable and consistent.
Only 2 tools is thin for a stock-image server; a search-plus-download pair is a reasonable minimal core, but it feels under-scoped for a domain that typically needs provider listing, metadata, and pagination.
The search-to-download workflow is covered, but there is no way to list providers or fetch image metadata/details, and search only exposes pexels while download accepts pexels/unsplash/pixabay, an inconsistency that hints at a partial surface.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
MCP server for Qwen Image 3 AI image generation
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for searching images with Google224 npm15MIT
- AlicenseAqualityDmaintenanceAn MCP server to search for photos and videos on Pexels.316 npmMIT
- AlicenseAqualityDmaintenanceMCP server that allows AI coding agents to search, download, and convert stock photos from Pexels, Unsplash, and Pixabay into WebP format for direct use in web development projects.35MIT
- AlicenseAqualityDmaintenanceMCP server that enables searching and downloading Unsplash photos and collections.4MIT