Unsplash MCP Server
This server provides a single tool to search Unsplash's photo library with customizable filters and pagination.
Search photos by keyword (e.g., "mountain")
Filter by color (e.g., black_and_white, blue, red, etc.)
Filter by orientation (landscape, portrait, squarish)
Sort results by relevance or latest
Control pagination (page number and results per page, up to 30)
Receive photo details including ID, description, image URLs, width, and height
Provides advanced image search capabilities for Unsplash's photo library, allowing filtering by keyword relevance, color schemes, orientation options, with custom sorting and pagination.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unsplash MCP Server search for landscape photos of mountains with blue color scheme"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unsplash MCP Server
English | 简体中文
A simple MCP server for seamless Unsplash image integration and search capabilities.
📋 Overview
Unsplash MCP Server is used for searching rich, high-quality images. It's ideal for developers who want to integrate Unsplash functionality into their own applications.
Related MCP server: Unsplash MCP Server
✨ Features
Advanced Image Search: Search Unsplash's extensive photo library with filters for:
Keyword relevance
Color schemes
Orientation options
Custom sorting and pagination
🔑 Obtaining Unsplash Access Key
Before installing this server, you'll need to obtain an Unsplash API Access Key:
Create a developer account at Unsplash
Register a new application
Get your Access Key from the application details page
Use this key in the configuration steps below
For more details, refer to the official Unsplash API documentation.
🚀 Installation
To install Unsplash Image Integration Server for Claude Desktop automatically via Smithery:
IDE Setup
Cursor IDE
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cursor --key 7558c683-****-****Windsurf
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client windsurf --key 7558c683-****-****Cline
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cline --key 7558c683-****-****Manual Installation
# 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 .Cursor Editor Integration
Add the following configuration to your Cursor editor's settings.json:
⚠️ Note: Please adjust the following configuration according to your actual installation:
If
uvis not in your system PATH, use an absolute path (e.g.,/path/to/uv)./server.pyshould be modified to the actual location of your server script (can use absolute path or path relative to workspace)
{
"mcpServers": {
"unsplash": {
"command": "uv",
"args": ["run", "--with", "fastmcp", "fastmcp", "run", "./server.py"],
"env": {
"UNSPLASH_ACCESS_KEY": "${YOUR_ACCESS_KEY}"
}
}
}
}Using in Cursor
🛠️ Available Tools
Search Photos
{
"tool": "search_photos",
"query": "mountain",
"per_page": 5,
"orientation": "landscape"
}🔄 Other Implementations
Golang: unsplash-mcp-server
Java: unsplash-mcp-server
📄 License
📬 Contact
Available Tools
1 toolsearch_photosA
Search for Unsplash photos
Args:
query: Search keyword
page: Page number (1-based)
per_page: Results per page (1-30)
order_by: Sort method (relevant or latest)
color: Color filter (black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue)
orientation: Orientation filter (landscape, portrait, squarish)
Returns:
List[UnsplashPhoto]: List of search results containing photo objects with the following properties:
- id: Unique identifier for the photo
- description: Optional text description of the photo
- urls: Dictionary of available image URLs in different sizes
- width: Original image width in pixels
- height: Original image height in pixels
Inputs: query (required), page, per_page, order_by, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap between tools. The single tool 'search_photos' has a clearly defined and distinct purpose.
The single tool follows a clear verb_noun pattern ('search_photos'), and with only one tool, there is perfect consistency by definition.
A single tool for an Unsplash server feels thin and incomplete for the domain. While search is a core function, typical photo services would include additional operations like getting photo details, downloading, or user-related actions.
The tool surface is severely incomplete for an Unsplash server. There are significant gaps: no ability to get photo details by ID, download photos, access user profiles, collections, or statistics. The server only supports search, which limits agent workflows.
Maintenance
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Unofficial Serper MCP — wraps the Serper Google Search API (serper.dev)
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables users to search for high-quality photos on Unsplash with support for advanced filtering by orientation and content safety. It provides formatted photo metadata and images in either base64-encoded format or as JSON with URLs via stdio transport.144 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables searching and downloading photos from Unsplash via the Unsplash API, with support for pagination, orientation filtering, and multiple resolutions.46 npm1MIT
- AlicenseAqualityDmaintenanceAn MCP server for searching and retrieving photos from Unsplash with proper attribution, designed for LLMs building content pages.338MIT
- AlicenseAqualityDmaintenanceMCP server that enables searching and downloading Unsplash photos and collections.4MIT