Unsplash MCP Server

1# Unsplash MCP Server
2 
3An MCP (Model Context Protocol) server for fetching photos from [Unsplash](https://unsplash.com) with **proper attribution**. Designed for LLMs building content pages that need properly credited images.
4 
5## Features
6 
7- **Search Photos** - Find photos by keyword with filters (color, orientation)
8- **Random Photos** - Get random photos for variety in content
9- **Download Tracking** - Compliant with Unsplash API guidelines
10- **Full Attribution** - Every photo includes ready-to-use attribution text and HTML
11- **LLM-Optimized** - Pre-formatted attribution strings for easy embedding
12 
13## Why This Server?
14 
15Unsplash requires proper attribution when using their photos. This server makes it easy by including:
16 
17- `attribution_text`: Plain text like "Photo by John Doe on Unsplash"
18- `attribution_html`: Full HTML with proper links for web pages
19 
20```html
21Photo by <a href="https://unsplash.com/@johndoe">John Doe</a> on <a href="https://unsplash.com">Unsplash</a>
22```
23 
24## Installation
25 
26### Prerequisites
27 
28- Python 3.11+
29- An Unsplash API access key ([Get one here](https://unsplash.com/developers))
30 
31### Quick Start
32 
33```bash
34# Clone the repository
35git clone https://github.com/cevatkerim/unsplash-mcp.git
36cd unsplash-mcp
37 
38# Create virtual environment
39python3 -m venv .venv
40source .venv/bin/activate
41 
42# Install dependencies
43pip install fastmcp httpx python-dotenv
44 
45# Set your API key
46echo "UNSPLASH_ACCESS_KEY=your_key_here" > .env
47 
48# Run the server
49fastmcp run server.py
50```
51 
52## Configuration
53 
54### Claude Code
55 
56Add to your `~/.claude.json` (user-level) or project `.mcp.json`:
57 
58```json
59{
60  "mcpServers": {
61    "unsplash": {
62      "type": "stdio",
63      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
64      "args": ["run", "/path/to/unsplash-mcp/server.py"],
65      "env": {
66        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
67      }
68    }
69  }
70}
71```
72 
73### Cursor
74 
75Add to your Cursor MCP settings:
76 
77```json
78{
79  "mcpServers": {
80    "unsplash": {
81      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
82      "args": ["run", "/path/to/unsplash-mcp/server.py"],
83      "env": {
84        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
85      }
86    }
87  }
88}
89```
90 
91### Windsurf / Cline
92 
93Add to your MCP configuration:
94 
95```json
96{
97  "unsplash": {
98    "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
99    "args": ["run", "/path/to/unsplash-mcp/server.py"],
100    "env": {
101      "UNSPLASH_ACCESS_KEY": "your_access_key_here"
102    }
103  }
104}
105```
106 
107## Tools
108 
109### `search_photos`
110 
111Search for photos by keyword with optional filters.
112 
113**Parameters:**
114| Parameter | Type | Default | Description |
115|-----------|------|---------|-------------|
116| `query` | string | required | Search keyword(s) |
117| `page` | int | 1 | Page number |
118| `per_page` | int | 10 | Results per page (1-30) |
119| `order_by` | string | "relevant" | Sort: "relevant" or "latest" |
120| `color` | string | null | Color filter (see below) |
121| `orientation` | string | null | "landscape", "portrait", "squarish" |
122| `content_filter` | string | "low" | Safety: "low" or "high" |
123 
124**Color options:** `black_and_white`, `black`, `white`, `yellow`, `orange`, `red`, `purple`, `magenta`, `green`, `teal`, `blue`
125 
126**Example:**
127```
128search_photos("mountain sunset", per_page=5, orientation="landscape")
129```
130 
131### `get_random_photos`
132 
133Get random photos, optionally filtered by keyword.
134 
135**Parameters:**
136| Parameter | Type | Default | Description |
137|-----------|------|---------|-------------|
138| `query` | string | null | Optional keyword filter |
139| `count` | int | 1 | Number of photos (1-30) |
140| `orientation` | string | null | "landscape", "portrait", "squarish" |
141| `content_filter` | string | "low" | Safety: "low" or "high" |
142 
143**Example:**
144```
145get_random_photos(query="nature", count=3, orientation="landscape")
146```
147 
148### `track_download`
149 
150Track a photo download (required by Unsplash API guidelines).
151 
152**Parameters:**
153| Parameter | Type | Description |
154|-----------|------|-------------|
155| `photo_id` | string | Photo ID from search results |
156 
157**Example:**
158```
159track_download("abc123xyz")
160```
161 
162## Response Format
163 
164Each photo includes:
165 
166```python
167{
168    "id": "abc123",
169    "description": "A beautiful mountain landscape",
170    "alt_description": "snow-capped mountains under blue sky",
171    "urls": {
172        "raw": "https://images.unsplash.com/...",
173        "full": "https://images.unsplash.com/...",
174        "regular": "https://images.unsplash.com/...",  # Recommended for web
175        "small": "https://images.unsplash.com/...",
176        "thumb": "https://images.unsplash.com/..."
177    },
178    "width": 4000,
179    "height": 3000,
180    "color": "#a3c4f3",  # Dominant color for placeholders
181    "blur_hash": "LKO2?U%2Tw=w...",  # For progressive loading
182 
183    # Attribution (REQUIRED when using the image)
184    "photographer_name": "John Doe",
185    "photographer_username": "johndoe",
186    "photographer_url": "https://unsplash.com/@johndoe?utm_source=...",
187    "photo_url": "https://unsplash.com/photos/abc123?utm_source=...",
188 
189    # Ready-to-use attribution
190    "attribution_text": "Photo by John Doe on Unsplash",
191    "attribution_html": "Photo by <a href=\"...\">John Doe</a> on <a href=\"...\">Unsplash</a>"
192}
193```
194 
195## Usage Example
196 
197When an LLM builds a content page:
198 
1991. Search for relevant images:
200   ```
201   photos = search_photos("coffee shop interior", per_page=5)
202   ```
203 
2042. Select a photo and use it:
205   ```html
206   <img src="{photo.urls.regular}" alt="{photo.alt_description}">
207   <p class="attribution">{photo.attribution_html}</p>
208   ```
209 
2103. If offering download, track it:
211   ```
212   download_url = track_download(photo.id)
213   ```
214 
215## Unsplash API Guidelines
216 
217This server helps you comply with [Unsplash API guidelines](https://unsplash.com/api-terms):
218 
2191. **Attribution** - Always credit the photographer and Unsplash (use `attribution_html`)
2202. **Hotlinking** - Use the provided URLs directly (enables view tracking)
2213. **Download tracking** - Call `track_download()` when users download images
222 
223## Rate Limits
224 
225- **Demo mode**: 50 requests/hour
226- **Production**: 5,000 requests/hour (after approval)
227 
228## License
229 
230MIT License - See [LICENSE](LICENSE) file.
231 
232## Contributing
233 
234Contributions welcome! Please feel free to submit a Pull Request.
235 
236## Support
237 
238If you find this project useful, consider buying me a coffee!
239 
240<a href="https://www.buymeacoffee.com/cevatkerim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
241 
242## Acknowledgments
243 
244- [Unsplash](https://unsplash.com) for providing an amazing free photo API
245- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework
246