joelio/stocky

Stocky is an MCP server that lets an AI
assistant search, inspect and download royalty-free stock photography from
**Pexels** and **Unsplash**.
> ### 🆕 Version 2.0 — already using Stocky? Read this
>
> **Your MCP client config keeps working.** If it points at stocky_mcp.py,
> that file is still there and still starts the server. Nothing breaks on
> upgrade.
>
> **But pip install -r requirements.txt will fail** — that file is gone, and
> so is setup.py. From a source checkout, install with **uv sync** or
> **pip install -e .** instead. See Upgrading from 1.x
> for the two-minute version, or the CHANGELOG for everything.
>
> The headline changes: pycurl is gone (so no more C build errors),
> searches actually run concurrently, failed providers now report *why*
> instead of returning nothing, and Python 3.10+ is required.
✨ Features
- 🔍 **Multi-provider search** — queries Pexels and Unsplash concurrently
- 📊 **Rich metadata** — dimensions, photographer, tags and every image size
- ⚖️ **Licence-aware** — generates the attribution each provider requires, and
reports Unsplash downloads as their API guidelines demand
- ⏱️ **Search caching** — a short TTL cache keeps repeat queries off your quota
- 🛡️ **Honest errors** — a failing provider is reported, not silently returned
as "no results"
- 🎯 **Filters** — orientation, colour and sort, validated per provider
**Beautiful stock photography at your fingertips**
Example image used for demonstration purposes
*Stunning landscapes available through multiple providers*
Photo by Simon Berger on Unsplash
🚀 Quick start
1. Get API keys
Both are free:
| Provider | Where | Notes |
|---|---|---|
| **Pexels** 📷 | pexels.com/api | 200 requests/hour by default |
| **Unsplash** 🌅 | unsplash.com/developers | 50/hour in demo mode, 1000/hour once your app is approved |
You only need one — Stocky runs with whichever providers are configured.
2. Add it to your MCP client
The recommended configuration needs no installation at all:
Other ways to run it
**Installed with pip or uv:**
**From a source checkout** — still supported so existing configurations keep
working:
Stocky reads its configuration from the environment its client starts it in.
It does not load a .env file of its own, so keys must go in the env block
above.
⚙️ Configuration
| Variable | Default | Purpose |
|---|---|---|
| PEXELS_API_KEY | — | Enables the Pexels provider |
| UNSPLASH_ACCESS_KEY | — | Enables the Unsplash provider |
| ENABLE_ATTRIBUTION_LINKS | false | Include attribution details in every result |
| STOCKY_CACHE_TTL | 300 | Search cache lifetime in seconds. 0 disables caching |
| STOCKY_HTTP_TIMEOUT | 15 | Per-request timeout in seconds |
| STOCKY_MAX_DOWNLOAD_BYTES | 26214400 | Refuse downloads larger than this (25 MiB) |
| STOCKY_DOWNLOAD_ROOT | — | If set, confine all downloads to this directory |
| STOCKY_LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR |
| STOCKY_USER_AGENT | stocky-mcp | User-Agent sent to providers |
STOCKY_DOWNLOAD_ROOT is worth setting. Download paths come from
model-generated tool calls, and this confines writes to one directory. Stocky
always refuses a non-image file extension, and validates that image URLs from a
provider are public HTTP(S) addresses before fetching them, but a download root
is the strongest control available.
📖 Usage
Find the perfect image for your project
Stocky exposes three **MCP tools**. You don't call them directly — your client
invokes them when you ask in natural language.
> Search stock photos for a misty pine forest at dawn.
> Find 30 landscape-orientation mountain photos from Pexels.
> Download pexels_123456 at medium size to ~/Pictures/mountain.jpg
🛠️ Tools
search_stock_images
| Parameter | Type | Default | Notes |
|---|---|---|---|
| query | str | *required* | Search terms |