Stocky
Find beautiful royalty-free stock images 📸

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"
      }
    }
  }
}

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

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

{
  "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.

⚙️ 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

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

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

⬆️ 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 problem rather than a Stocky bug. GUI-launched clients often have a minimal PATH, so uvx or a virtualenv python may not be found — use an absolute path, or uvx with uv installed system-wide. You can reproduce the handshake yourself:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | stocky-mcp

A JSON response means the server is fine. Note that stdout carries the protocol, so Stocky sends all logging to stderr — anything else printed there would corrupt the stream.

"No image providers are configured" No keys reached the server. They must be in the env block of your client config; names are case-sensitive.

A provider returns an error Check errors in the response. Auth failures, rate limits and timeouts are now reported explicitly rather than looking like an empty result set.

Pexels seems to accept an invalid key It does. Pexels returns 200 for a malformed key, so a typo can look like it works. If results seem wrong, verify the key directly.

Rate limits

🤝 Contributing

Contributions are welcome — see CONTRIBUTING.md. For major changes, please open an issue first to discuss the approach.

🙏 Acknowledgments

• Thanks to Pexels and Unsplash for their free APIs
• Built with the Model Context Protocol