cevatkerim/unsplash-mcp

An MCP (Model Context Protocol) server for fetching photos from Unsplash with **proper attribution**. Designed for LLMs building content pages that need properly credited images.
Features
- **Search Photos** - Find photos by keyword with filters (color, orientation)
- **Random Photos** - Get random photos for variety in content
- **Download Tracking** - Compliant with Unsplash API guidelines
- **Full Attribution** - Every photo includes ready-to-use attribution text and HTML
- **LLM-Optimized** - Pre-formatted attribution strings for easy embedding
Why This Server?
Unsplash requires proper attribution when using their photos. This server makes it easy by including:
- attribution_text: Plain text like "Photo by John Doe on Unsplash"
- attribution_html: Full HTML with proper links for web pages
Installation
Prerequisites
- Python 3.11+
- An Unsplash API access key (Get one here)
Quick Start
Configuration
Claude Code
Add to your ~/.claude.json (user-level) or project .mcp.json:
Cursor
Add to your Cursor MCP settings:
Windsurf / Cline
Add to your MCP configuration:
Tools
search_photos
Search for photos by keyword with optional filters.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| query | string | required | Search keyword(s) |
| page | int | 1 | Page number |
| per_page | int | 10 | Results per page (1-30) |
| order_by | string | "relevant" | Sort: "relevant" or "latest" |
| color | string | null | Color filter (see below) |
| orientation | string | null | "landscape", "portrait", "squarish" |
| content_filter | string | "low" | Safety: "low" or "high" |
**Color options:** black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue
**Example:**
get_random_photos
Get random photos, optionally filtered by keyword.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| query | string | null | Optional keyword filter |
| count | int | 1 | Number of photos (1-30) |
| orientation | string | null | "landscape", "portrait", "squarish" |
| content_filter | string | "low" | Safety: "low" or "high" |
**Example:**
track_download
Track a photo download (required by Unsplash API guidelines).
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| photo_id | string | Photo ID from search results |
**Example:**
Response Format
Each photo includes:
Usage Example
When an LLM builds a content page:
1. Search for relevant images:
2. Select a photo and use it:
3. If offering download, track it: