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

<div align="center">

  

</div>

✨ 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

!Photography Example

Beautiful stock photography at your fingertips Example image used for demonstration purposes

!Mountain Landscape Stunning landscapes available through multiple providers

Photo by Simon Berger on Unsplash

🚀 Quick Start

Installation

1. Clone the repository:

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

1. Install dependencies:

pip install -r requirements.txt

API Key Setup

You'll need free API keys from each provider:

1. Pexels 📷 - Get your key at pexels.com/api
2. 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:

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

<div align="center"> <img src="images/photography-example2.jpg" alt="Stock Photography Example" width="600"> <p><em>Find the perfect image for your project</em></p> </div>

Stocky exposes search_stock_images, get_image_details, and download_image as MCP tools. They are not Python functions you import and call — your MCP client (e.g. Claude Desktop) invokes them on your behalf when you ask in natural language. The parameters below map to each tool's arguments.

Searching for Images

Just ask your assistant, for example:

Search stock photos for a sunset beach.

Find 30 mountain landscape photos from Pexels and Unsplash.

These map to the search_stock_images tool. The arguments a client sends look like:

{
  "query": "mountain landscape",
  "providers": ["pexels", "unsplash"],
  "per_page": 30,
  "page": 1
}

Getting Image Details

Get the details for image unsplash_abc123xyz.

Maps to get_image_details with {"image_id": "unsplash_abc123xyz"}.

Downloading Images

Download pexels_123456 at medium size to /path/to/save.jpg.

Maps to download_image:

{
  "image_id": "pexels_123456",
  "size": "medium",
  "output_path": "/path/to/save.jpg"
}

If output_path is omitted, the tool returns base64-encoded image data instead of writing a file.

Calling the tools programmatically

To drive the tools from Python, connect to the server through an MCP client session over stdio rather than importing these names. See test_mcp_client.py for a complete, runnable example.

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

<div align="center"> <img src="images/photography-example3.jpg" alt="License Information" width="600"> <p><em>Royalty-free images for your creative projects</em></p> </div>

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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. 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

• Set the keys in the env block of your MCP client configuration (see

MCP Client Configuration) — the server reads them from its environment and does not load a .env file on its own

• Verify API key names match exactly (case-sensitive): PEXELS_API_KEY,

UNSPLASH_ACCESS_KEY

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)

---

<div align="center"> Made with 💜 by the Stocky Team </div>