- 🔍 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
Add this skill
npx mdskills install joelio/stockyWell-documented MCP server providing multi-provider stock image search with clear setup and API docs
1# <div align="center"><br/>Stocky<br/>*Find beautiful royalty-free stock images* 📸</div>23<div align="center">45[](https://www.python.org/downloads/)6[](https://github.com/modelcontextprotocol)7[](https://opensource.org/licenses/MIT)89</div>1011## ✨ Features1213- 🔍 **Multi-Provider Search** - Search across Pexels and Unsplash simultaneously14- 📊 **Rich Metadata** - Get comprehensive image details including dimensions, photographer info, and licensing15- 📄 **Pagination Support** - Browse through large result sets with ease16- 🛡️ **Graceful Error Handling** - Robust error handling for API failures17- ⚡ **Async Performance** - Lightning-fast concurrent API calls18- 🎯 **Provider Flexibility** - Search specific providers or all at once19202122**Beautiful stock photography at your fingertips**23Example image used for demonstration purposes242526*Stunning landscapes available through multiple providers*2728Photo by [Simon Berger](https://unsplash.com/@simon_berger) on [Unsplash](https://unsplash.com/photos/twukN12EN7c)2930## 🚀 Quick Start3132### Installation33341. Clone the repository:35```bash36git clone https://github.com/yourusername/stocky-mcp.git37cd stocky-mcp38```39402. Install dependencies:41```bash42pip install -r requirements.txt43```4445### API Key Setup4647You'll need free API keys from each provider:48491. **Pexels** 📷 - Get your key at [pexels.com/api](https://www.pexels.com/api/)502. **Unsplash** 🌅 - Sign up at [unsplash.com/developers](https://unsplash.com/developers)515253### API Key Configuration5455You'll need to configure your API keys when setting up the MCP server. These keys are used to authenticate with the stock image providers.5657### Running as an MCP Server5859Stocky 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.6061## 🔧 MCP Client Configuration6263Add Stocky to your MCP client configuration:6465```json66{67 "mcpServers": {68 "stocky": {69 "command": "python",70 "args": ["/path/to/stocky_mcp.py"],71 "env": {72 "PEXELS_API_KEY": "your_pexels_key",73 "UNSPLASH_ACCESS_KEY": "your_unsplash_key",7475 }76 }77 }78}79```8081## 📖 Usage Examples8283<div align="center">84<img src="images/photography-example2.jpg" alt="Stock Photography Example" width="600">85<p><em>Find the perfect image for your project</em></p>86</div>8788### Searching for Images8990Search across all providers:91```python92results = await search_stock_images("sunset beach")93```9495Search specific providers:96```python97results = await search_stock_images(98 query="mountain landscape",99 providers=["pexels", "unsplash"],100 per_page=30,101 page=1102)103```104105### Getting Image Details106107```python108details = await get_image_details("unsplash_abc123xyz")109```110111### Downloading Images112113```python114# Download and save to disk115result = await download_image(116 image_id="pexels_123456",117 size="medium",118 output_path="/path/to/save.jpg"119)120121# Get base64-encoded image data122result = await download_image(123 image_id="unsplash_abc123",124 size="original"125)126```127128## 🛠️ Tools Documentation129130### `search_stock_images`131132Search for royalty-free stock images across multiple providers.133134**Parameters:**135- `query` (str, required) - Search terms for finding images136- `providers` (list, optional) - List of providers to search: `["pexels", "unsplash"]`137- `per_page` (int, optional) - Results per page, max 50 (default: 20)138- `page` (int, optional) - Page number for pagination (default: 1)139- `sort_by` (str, optional) - Sort results by "relevance" or "newest"140141**Returns:** List of image results with metadata142143### `get_image_details`144145Get detailed information about a specific image.146147**Parameters:**148- `image_id` (str, required) - Image ID in format `provider_id` (e.g., `pexels_123456`)149150**Returns:** Detailed image information including full metadata151152### `download_image`153154Download an image to local storage or get base64 encoded data.155156**Parameters:**157- `image_id` (str, required) - Image ID in format `provider_id` (e.g., `pexels_123456`)158- `size` (str, optional) - Image size variant to download (default: "original")159 - Options: thumbnail, small, medium, large, original160- `output_path` (str, optional) - Path to save the image locally161 - If not provided, returns base64 encoded image data162163**Returns:** Dictionary with download information or error164165## 📄 License Information166167<div align="center">168<img src="images/photography-example3.jpg" alt="License Information" width="600">169<p><em>Royalty-free images for your creative projects</em></p>170</div>171172All images returned by Stocky are free to use:173174- **Pexels** ✅ - Free for commercial and personal use, no attribution required175- **Unsplash** ✅ - Free under the Unsplash License176177178Always check the specific license for each image before use in production.179180## 🤝 Contributing181182Contributions 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.1831841. Fork the Project1852. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)1863. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)1874. Push to the Branch (`git push origin feature/AmazingFeature`)1885. Open a Pull Request189190## 🙏 Acknowledgments191192- Thanks to [Pexels](https://www.pexels.com) and [Unsplash](https://unsplash.com) for providing free APIs193- Built with the [Model Context Protocol](https://github.com/modelcontextprotocol)194- Created with ❤️ for the developer community195196## 🐛 Troubleshooting197198### Common Issues199200**"API key not found" error**201- Ensure your `.env` file exists and contains valid API keys202- Check that environment variables are properly loaded203- Verify API key names match exactly (case-sensitive)204205**No results returned**206- Try different search terms207- Check your internet connection208- Verify API keys are active and have not exceeded rate limits209210**Installation issues**211- Ensure Python 3.8+ is installed212- Try creating a virtual environment: `python -m venv venv`213- Update pip: `pip install --upgrade pip`214215### Rate Limiting216217Each provider has different rate limits:218- **Pexels**: 200 requests per hour219- **Unsplash**: 50 requests per hour (demo), 5000 per hour (production)220221222---223224<div align="center">225Made with 💜 by the Stocky Team226</div>227
Full transparency — inspect the skill content before installing.