Stocky

<div align="center"><br/>Stocky<br/>Find beautiful royalty-free stock images 📸</div>

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:

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:

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key",
        "UNSPLASH_ACCESS_KEY": "your_unsplash_key"
      }
    }
  }
}

Installed with pip or uv:

uv tool install stocky-mcp     # or: pipx install stocky-mcp

{
  "mcpServers": {
    "stocky": {
      "command": "stocky-mcp",
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

From a source checkout — still supported so existing configurations keep working:

{
  "mcpServers": {
    "stocky": {
      "command": "python",
      "args": ["/path/to/stocky/stocky_mcp.py"],
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

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.

<a id="configuration"></a>

⚙️ Configuration

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

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

Returns results grouped by provider, plus total_results and — if any provider failed — an errors map explaining which and why.

An invalid orientation or color is dropped rather than forwarded: Pexels silently ignores bad filters and still returns 200, which would otherwise hide the mistake, while Unsplash rejects them outright with HTTP 400.

get_image_details

download_image

If a provider doesn't offer the requested size, the closest available one is used rather than failing.

Resource

stock-images://help — a usage guide the assistant can read on demand.

⚖️ Licence and attribution

Images are free to use, but both providers require attribution as a condition of API access. This is not optional, and the previous version of this document was wrong to imply otherwise for Pexels.

Pexels requires a prominent link back to Pexels wherever API results are shown, and asks that you credit the photographer where possible.

Unsplash requires that you credit both the photographer and Unsplash, with UTM parameters on the links, and that images are hotlinked from the URLs the API returns rather than re-hosted.

Set ENABLE_ATTRIBUTION_LINKS=true and each result gains an attribution block with ready-made text and html in the correct format for its provider.

Note on download_image. Saving Unsplash bytes to disk or returning them base64-encoded is in tension with Unsplash's hotlinking requirement. Stocky fires the mandatory download-report endpoint whenever you download an Unsplash image, but if you are displaying images in an application, use the hotlinked URLs from the search results instead of downloading them.

Read the full terms: Pexels · Unsplash

<a id="upgrading"></a>

⬆️ Upgrading from 1.x

Version 2.0 restructured the project. Existing MCP client configurations keep working — the root stocky_mcp.py is deliberately retained as a launcher — but installation changed, and a few behaviours are intentionally different.

What you need to do

If you run it via uvx or an installed console script, nothing. Upgrade and carry on.

If you run it from a source checkout, reinstall. requirements.txt, setup.py and setup.cfg were replaced by pyproject.toml:

git pull
uv sync                     # or: pip install -e .

pip install -r requirements.txt now fails — the file no longer exists.

Check your Python version. 2.0 requires Python 3.10+. The old setup.py claimed 3.8 support, but the mcp SDK has always required 3.10, so that claim was never actually satisfiable.

Consider switching to uvx. It needs nothing installed and avoids the whole class of "which interpreter did my editor launch?" startup failures:

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

What changed underneath

The one thing that might affect your code

Only if you parse Stocky's responses programmatically. A search that fails now returns an errors map naming the provider and the reason, where it used to return an empty result list:

{
  "query": "mountains",
  "results": { "pexels": [], "unsplash": [ /* ... */ ] },
  "errors": { "pexels": "pexels rejected the API key (HTTP 401)..." }
}

If you treated "empty" as "no matches", check for errors too — otherwise a broken key looks like a query with no results. This is the fix, not a regression, but it is a visible change.

Nothing else in the tool surface changed: search_stock_images, get_image_details and download_image take the same arguments they always did, so existing prompts and workflows are unaffected.

🧑‍💻 Development

git clone https://github.com/joelio/stocky.git
cd stocky
uv sync --group dev

uv run pytest -m "not integration"   # unit tests, no network
uv run pytest -m integration         # needs real API keys
uv run ruff check . && uv run ruff format --check .
uv run mypy

See CONTRIBUTING.md for more.

🐛 Troubleshooting

Client reports a timeout on startup Almost always a launch

…