search_photos
Search for Unsplash photos
LABSCO SUMMARY
Choosing a stock photo stops being a tab switch.
One tool with six arguments, and the arguments are the reason to install it: colour and orientation are what turn a search into a shortlist for a specific slot in a layout, while page and per_page keep the response small enough to read in a conversation. There is nothing here past search — no download, no attribution helper, no collections — so it belongs in a workflow that already knows what to do with a photo once it has one.
What it is
A single-tool server over Unsplash photo search.
What you get
- Photo search by query, narrowed by colour and by orientation
- Result ordering under your control through order_by rather than fixed to relevance
- Pagination with page and per_page, so a shortlist can be walked without re-running the search
Requirements
uv with a Python available, and an Unsplash Access Key in UNSPLASH_ACCESS_KEY, taken from an application in your Unsplash developer account.
Setup effort
Build from source — git clone https://github.com/hellokaton/unsplash-mcp-server.git
USE CASES
01
Finding a header image that fits the palette
Search on the subject, constrain the result by colour and by orientation so what comes back suits the slot it has to fill, and page through rather than re-running the query.
1 tool
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
BEFORE YOU INSTALL
What to know first
Tools you get
1 tool when we connected.
Requires
- UNSPLASH_ACCESS_KEY in your environment
- for the Windsurf and Cline routes, which install through Smithery: a Smithery account and its API key
CONTEXT COST
Light Standing cost
Rated by the size of the one tool definition that rides along on every turn
INSTALLATION
Connect your client
Server setup
TERMINAL
# Clone the repository
git clone https://github.com/hellokaton/unsplash-mcp-server.git
# Navigate to project directory
cd unsplash-mcp-server
# Create virtual environment
uv venv
# Install dependencies
uv pip install .MCP Clients
Cursor
CURSOR · JSON
{
"mcpServers": {
"unsplash": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"./server.py"
],
"env": {
"UNSPLASH_ACCESS_KEY": "<YOUR_UNSPLASH_ACCESS_KEY>"
}
}
}
}<YOUR_UNSPLASH_ACCESS_KEY> is your Unsplash Access Key, and change ./server.py to the full path of server.py in the folder you cloned — a relative path is resolved from wherever Cursor starts the server. If uv is not on your PATH, use its absolute path (for example /path/to/uv) as the command.
Windsurf
WINDSURF · TERMINAL
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client windsurf --key <YOUR_SMITHERY_API_KEY>This installs the server through Smithery, so it needs a Smithery account: <YOUR_SMITHERY_API_KEY> is the API key from your account at smithery.ai. Your Unsplash Access Key is still needed as well.
Cline
CLINE · TERMINAL
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cline --key <YOUR_SMITHERY_API_KEY>This installs the server through Smithery, so it needs a Smithery account: <YOUR_SMITHERY_API_KEY> is the API key from your account at smithery.ai. Your Unsplash Access Key is still needed as well.
