Stocky

Find beautiful royalty-free stock images across multiple providers in one search.

Stars

Forks

Watchers

Issues

Stocky enables fast, asynchronous search and retrieval of royalty-free stock images from Pexels and Unsplash through a unified MCP-compatible interface. It supports rich metadata, provider flexibility, pagination, and robust error handling. Designed to operate as an MCP (Model Context Protocol) server, it integrates with MCP clients using standard client configuration and environment variables for API keys. Stocky provides Python async functions for searching, retrieving details, and downloading images with flexible output options.

Key Features

Multi-provider search support (Pexels and Unsplash)

Rich metadata retrieval including image details and licensing

Flexible provider selection

Pagination for browsing large result sets

Graceful error handling

Async performance with fast concurrent API calls

MCP server compatibility

Python async functions for search and download

Environment variable API key configuration

Multiple image download formats (file or base64)

Use Cases

Integrating curated image search and sourcing into AI or chatbot applications

Dynamically fetching images for content creation tools

Building custom MCP clients that access stock photography across multiple providers

Rapid prototyping of web or mobile apps needing high-quality royalty-free images

Automating the process of fetching and downloading images for design projects

Aggregating image metadata for research or analytics purposes

Batch downloading photos for offline use or datasets

Powering automated creative pipelines in marketing tech

Supporting context-aware image recommendations in digital products

Enhancing documentation or knowledge bases with dynamic image sourcing

README

StockyFind beautiful royalty-free stock images 📸

✨ Features

🔍 Multi-Provider Search - Search across Pexels and Unsplash simultaneously
📊 Rich Metadata - Get comprehensive image details including dimensions, photographer info, and licensing
📄 Pagination Support - Browse through large result sets with ease
🛡️ Graceful Error Handling - Robust error handling for API failures
⚡ Async Performance - Lightning-fast concurrent API calls
🎯 Provider Flexibility - Search specific providers or all at once

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

Installation

Clone the repository:

bash

git clone https://github.com/yourusername/stocky-mcp.git
cd stocky-mcp

Install dependencies:

bash

pip install -r requirements.txt

API Key Setup

You'll need free API keys from each provider:

Pexels 📷 - Get your key at pexels.com/api
Unsplash 🌅 - Sign up at unsplash.com/developers

API Key Configuration

You'll need to configure your API keys when setting up the MCP server. These keys are used to authenticate with the stock image providers.

Running as an MCP Server

Stocky is designed to be run as an MCP (Model Context Protocol) server, not as a standalone application. It should be configured in your MCP client configuration.

🔧 MCP Client Configuration

Add Stocky to your MCP client configuration:

json

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

      }
    }
  }
}

📖 Usage Examples

Searching for Images

Search across all providers:

python

results = await search_stock_images("sunset beach")

Search specific providers:

python

results = await search_stock_images(
    query="mountain landscape",
    providers=["pexels", "unsplash"],
    per_page=30,
    page=1
)

Getting Image Details

python

details = await get_image_details("unsplash_abc123xyz")

Downloading Images

python

# Download and save to disk
result = await download_image(
    image_id="pexels_123456", 
    size="medium", 
    output_path="/path/to/save.jpg"
)

# Get base64-encoded image data
result = await download_image(
    image_id="unsplash_abc123", 
    size="original"
)

🛠️ Tools Documentation

`search_stock_images`

Search for royalty-free stock images across multiple providers.

Parameters:

query (str, required) - Search terms for finding images
providers (list, optional) - List of providers to search: ["pexels", "unsplash"]
per_page (int, optional) - Results per page, max 50 (default: 20)
page (int, optional) - Page number for pagination (default: 1)
sort_by (str, optional) - Sort results by "relevance" or "newest"

Returns: List of image results with metadata

`get_image_details`

Get detailed information about a specific image.

Parameters:

image_id (str, required) - Image ID in format provider_id (e.g., pexels_123456)

Returns: Detailed image information including full metadata

`download_image`

Download an image to local storage or get base64 encoded data.

Parameters:

image_id (str, required) - Image ID in format provider_id (e.g., pexels_123456)
size (str, optional) - Image size variant to download (default: "original")
- Options: thumbnail, small, medium, large, original
output_path (str, optional) - Path to save the image locally
- If not provided, returns base64 encoded image data

Returns: Dictionary with download information or error

📄 License Information

All images returned by Stocky are free to use:

Pexels ✅ - Free for commercial and personal use, no attribution required
Unsplash ✅ - Free under the Unsplash License

Always check the specific license for each image before use in production.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

🙏 Acknowledgments

Thanks to Pexels and Unsplash for providing free APIs
Built with the Model Context Protocol
Created with ❤️ for the developer community

🐛 Troubleshooting

Common Issues

"API key not found" error

Ensure your .env file exists and contains valid API keys
Check that environment variables are properly loaded
Verify API key names match exactly (case-sensitive)

No results returned

Try different search terms
Check your internet connection
Verify API keys are active and have not exceeded rate limits

Installation issues

Ensure Python 3.8+ is installed
Try creating a virtual environment: python -m venv venv
Update pip: pip install --upgrade pip

Rate Limiting

Each provider has different rate limits:

Pexels: 200 requests per hour
Unsplash: 50 requests per hour (demo), 5000 per hour (production)

Star History

Repository Owner

joelio

User

Repository Details

Language Python

Default Branch main

Size 3,322 KB

Contributors 3

License MIT License

MCP Verified Nov 12, 2025

Programming Languages

Python

100%

Related MCPs

Discover similar Model Context Protocol servers

NyxDocs

MCP server for real-time cryptocurrency project documentation and insights.

NyxDocs is a Model Context Protocol (MCP) compatible server built in Python for managing and serving up-to-date documentation for cryptocurrency projects. It aggregates information from multiple sources such as CoinGecko, GitHub, GitBook, Notion, and official websites, providing real-time data and updates on blockchain ecosystems. Featuring tools for searching projects, retrieving detailed info, extracting documentation, and monitoring changes, it is tailored for developers and AI contexts needing access to accurate crypto documentation. The architecture leverages a FastMCP-based server core, automated document scrapers, and supports multi-blockchain environments.

⭐ 3
MCP
nyxn-ai/NyxDocs

DuckDuckGo Search MCP Server

A Model Context Protocol server for DuckDuckGo web search and intelligent content retrieval.

DuckDuckGo Search MCP Server provides web search capabilities through DuckDuckGo, with advanced content fetching and parsing tailored for large language models. It supports rate limiting, error handling, and delivers results in an LLM-friendly format. The server is designed for seamless integration with AI applications and tools like Claude Desktop, enabling enhanced web search and content extraction through the Model Context Protocol.

⭐ 637
MCP
nickclyde/duckduckgo-mcp-server

Bing Search MCP Server

MCP server enabling Bing-powered web, news, and image search for AI assistants.

Bing Search MCP Server provides a Model Context Protocol (MCP) compliant interface for integrating Microsoft Bing Search API capabilities with AI assistants. The server allows AI clients to perform web, news, and image searches programmatically, with features like rate limiting and comprehensive error handling. Designed for easy deployment, it supports integration with clients such as Claude Desktop and Cursor for enhanced search access. Secure configuration via environment variables enables safe use of API keys.

⭐ 65
MCP
leehanchung/bing-search-mcp

ZoomEye MCP Server

Real-time cyberspace asset intelligence for AI assistants via Model Context Protocol.

ZoomEye MCP Server implements the Model Context Protocol (MCP) to provide network asset intelligence to AI assistants and development tools. It enables querying of global internet assets through ZoomEye's cyber asset search engine using structured parameters and dorks. The server includes features like caching, error handling, and compatibility with leading MCP environments, supporting real-time cyber asset data integration for various AI and developer platforms.

⭐ 50
MCP
zoomeye-ai/mcp_zoomeye

tavily-search MCP server

A search server that integrates Tavily API with Model Context Protocol tools.

tavily-search MCP server provides an MCP-compliant server to perform search queries using the Tavily API. It returns search results in text format, including AI responses, URLs, and result titles. The server is designed for easy integration with clients like Claude Desktop or Cursor and supports both local and Docker-based deployment. It facilitates AI workflows by offering search functionality as part of a standardized protocol interface.

⭐ 44
MCP
Tomatio13/mcp-server-tavily

Brave Search MCP Server

MCP integration for web, image, news, video, and local search via Brave Search API.

Implements a Model Context Protocol server that connects with the Brave Search API, enabling AI systems to perform comprehensive web, image, news, video, and local points of interest searches. Provides standardized MCP tools for various search types, each supporting advanced filtering parameters. Designed for easy integration in context-aware model interfaces such as Claude Code.

⭐ 86
MCP
mikechao/brave-search-mcp

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

Stocky

Key Features

Use Cases

README

StockyFind beautiful royalty-free stock images 📸

✨ Features

🚀 Quick Start

Installation

API Key Setup

API Key Configuration

Running as an MCP Server

🔧 MCP Client Configuration

📖 Usage Examples

Searching for Images

Getting Image Details

Downloading Images

🛠️ Tools Documentation

`search_stock_images`

`get_image_details`

`download_image`

📄 License Information

🤝 Contributing

🙏 Acknowledgments

🐛 Troubleshooting

Common Issues

Rate Limiting

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Related MCPs