Unsplash MCP Server

1[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/hellokaton-unsplash-mcp-server-badge.png)](https://mseep.ai/app/hellokaton-unsplash-mcp-server)
2 
3# Unsplash MCP Server
4 
5English | [简体中文](README_zh.md)
6 
7> A simple MCP server for seamless Unsplash image integration and search capabilities.
8 
9[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
10[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11[![smithery badge](https://smithery.ai/badge/@hellokaton/unsplash-mcp-server)](https://smithery.ai/server/@hellokaton/unsplash-mcp-server)
12 
13## 📋 Overview
14 
15Unsplash 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.
16 
17## ✨ Features
18 
19- **Advanced Image Search**: Search Unsplash's extensive photo library with filters for:
20  - Keyword relevance
21  - Color schemes
22  - Orientation options
23  - Custom sorting and pagination
24 
25## 🔑 Obtaining Unsplash Access Key
26 
27Before installing this server, you'll need to obtain an Unsplash API Access Key:
28 
291. Create a developer account at [Unsplash](https://unsplash.com/developers)
302. Register a new application
313. Get your Access Key from the application details page
324. Use this key in the configuration steps below
33 
34For more details, refer to the [official Unsplash API documentation](https://unsplash.com/documentation).
35 
36## 🚀 Installation
37 
38To install Unsplash Image Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@hellokaton/unsplash-mcp-server):
39 
40### IDE Setup
41 
42**Cursor IDE**
43 
44```bash
45npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cursor --key 7558c683-****-****
46```
47 
48**Windsurf**
49 
50```bash
51npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client windsurf --key 7558c683-****-****
52```
53 
54**Cline**
55 
56```bash
57npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cline --key 7558c683-****-****
58```
59 
60### Manual Installation
61 
62```bash
63# Clone the repository
64git clone https://github.com/hellokaton/unsplash-mcp-server.git
65 
66# Navigate to project directory
67cd unsplash-mcp-server
68 
69# Create virtual environment
70uv venv
71 
72# Install dependencies
73uv pip install .
74```
75 
76**Cursor Editor Integration**
77 
78Add the following configuration to your Cursor editor's `settings.json`:
79 
80⚠️ **Note:** Please adjust the following configuration according to your actual installation:
81 
82- If `uv` is not in your system PATH, use an absolute path (e.g., `/path/to/uv`)
83- `./server.py` should be modified to the actual location of your server script (can use absolute path or path relative to workspace)
84 
85<img src="screenshots/Snipaste_1.png" alt="Cursor Configuration Screenshot" />
86 
87```json
88{
89  "mcpServers": {
90    "unsplash": {
91      "command": "uv",
92      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "./server.py"],
93      "env": {
94        "UNSPLASH_ACCESS_KEY": "${YOUR_ACCESS_KEY}"
95      }
96    }
97  }
98}
99```
100 
101### Using in Cursor
102 
103<img src="screenshots/Snipaste_2.png" alt="Unsplash MCP in Cursor" />
104 
105## 🛠️ Available Tools
106 
107### Search Photos
108 
109```json
110{
111  "tool": "search_photos",
112  "query": "mountain",
113  "per_page": 5,
114  "orientation": "landscape"
115}
116```
117 
118## 🔄 Other Implementations
119 
120- Golang: [unsplash-mcp-server](https://github.com/douglarek/unsplash-mcp-server)
121- Java: [unsplash-mcp-server](https://github.com/JavaProgrammerLB/unsplash-mcp-server)
122 
123## 📄 License
124 
125[MIT License](LICENSE)
126 
127## 📬 Contact
128 
129- [Twitter/X](https://x.com/hellokaton)
130- [GitHub Issues](https://github.com/hellokaton/unsplash-mcp-server/issues)
131