Stocky

by joelio

358 downloads

Not rated

GitHub

Other

About

Stocky is a Model Context Protocol (MCP) server that searches and retrieves royalty-free stock images from multiple providers (Pexels and Unsplash) simultaneously. It is built for Python developers who need to find stock photos with rich metadata inside MCP-enabled applications.

Details

Author: joelio
Downloads: 358
Categories: Other

- Multi-provider search across Pexels and Unsplash simultaneously.
- Rich image metadata including dimensions, photographer info, and licensing.
- Pagination support for browsing large result sets.
- Graceful error handling for API failures.
- Async performance with concurrent API calls.
- Provider flexibility – search all providers or a specific one.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Stocky

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Install Stocky by cloning its repository, installing dependencies with pip install -r requirements.txt, and adding Pexels and Unsplash API keys to a .env file. Run the server with python stocky_mcp.py, then configure your MCP client to launch the script with the required environment variables. Use the search_stock_images tool to find images and get_image_details to retrieve full metadata for a specific image.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

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

</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

🚀 Quick Start

Installation

1. Clone the repository:

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

cd stocky-mcp

2. 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

Environment Configuration

1. Copy the example environment file:

cp .env.example .env

2. Add your API keys to .env:

PEXELS_API_KEY=your_pexels_key_here

UNSPLASH_ACCESS_KEY=your_unsplash_key_here

Running the Server

python stocky_mcp.py

🔧 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

Searching for Images

Search across all providers:

results = await search_stock_images("sunset beach")

Search specific providers:

results = await search_stock_images(

    query="mountain landscape",

    providers=["pexels", "unsplash"],

    per_page=30,

    page=1

)

Getting Image Details

details = await get_image_details("unsplash_abc123xyz")

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

📄 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.

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
- 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)

---

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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

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

✨ Features

🚀 Quick Start

Installation

API Key Setup

Environment Configuration

Running the Server

🔧 MCP Client Configuration

📖 Usage Examples

Searching for Images

Getting Image Details

🛠️ Tools Documentation

search_stock_images

get_image_details

📄 License Information

🤝 Contributing

🙏 Acknowledgments

🐛 Troubleshooting

Common Issues

Rate Limiting

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`search_stock_images`

`get_image_details`