https://github.com/hellokaton/unsplash-mcp-server
A MCP server for Unsplash image search and utilities.
https://github.com/hellokaton/unsplash-mcp-server
mcp-server python3 unsplash-mcp
Last synced: 8 months ago
JSON representation
A MCP server for Unsplash image search and utilities.
- Host: GitHub
- URL: https://github.com/hellokaton/unsplash-mcp-server
- Owner: hellokaton
- License: mit
- Created: 2025-03-18T08:42:50.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-18T10:10:05.000Z (8 months ago)
- Last Synced: 2025-03-18T10:25:37.452Z (8 months ago)
- Topics: mcp-server, python3, unsplash-mcp
- Language: Python
- Homepage:
- Size: 185 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - hellokaton/unsplash-mcp-server - An MCP server for Unsplash image search, allowing image retrieval within the MCP server architecture. ([Read more](/details/hellokatonunsplash-mcp-server.md)) `mcp` `image-search` `unsplash` `search` (API Integration MCP Servers)
- awesome-mcp-servers - **unsplash-mcp-server** - ๐ A MCP server for Unsplash image search. `python` `mcp-server` `python3` `unsplash-mcp` `mcp` `pip install git+https://github.com/hellokaton/unsplash-mcp-server` (๐ค AI/ML)
- awesome-mcp-servers - **unsplash-mcp-server** - ๐ A MCP server for Unsplash image search. `python` `mcp-server` `python3` `unsplash-mcp` `mcp` `pip install git+https://github.com/hellokaton/unsplash-mcp-server` (AI/ML)
- awesome-mcp-zh - hellokaton/unsplash-mcp-server
- best-of-mcp-servers - GitHub - 14% open ยท โฑ๏ธ 07.07.2025) (Search & Data Extraction)
- awesome-mcp-servers - Unsplash Image Server - ๐ A MCP server for Unsplash image search. (Table of Contents / Search)
- awesome-mcp-servers - Unsplash Image Server - ๐ A MCP server for Unsplash image search. (Table of Contents / Search)
- awesome-mcp-servers - hellokaton/unsplash-mcp-server - Unsplash ็ปๅๆค็ดขๆฉ่ฝใฎ็ตฑๅ็จ (ใตใผใใผๅฎ่ฃ / ๐ <a name="search"></a>ๆค็ดขใปใใผใฟๆฝๅบ)
- awesome-hacking-lists - hellokaton/unsplash-mcp-server - ๐ A MCP server for Unsplash image search. (Python)
- metorial-index - Unsplash Search - Connects to Unsplash's image library to perform advanced searches and apply filters on keywords for rich, high-quality image retrieval. (Web Search)
README
# Unsplash MCP Server
English | [็ฎไฝไธญๆ](README_zh.md)
> A simple MCP server for seamless Unsplash image integration and search capabilities.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://smithery.ai/server/@hellokaton/unsplash-mcp-server)
## ๐ 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.
## โจ 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:
1. Create a developer account at [Unsplash](https://unsplash.com/developers)
2. Register a new application
3. Get your Access Key from the application details page
4. Use this key in the configuration steps below
For more details, refer to the [official Unsplash API documentation](https://unsplash.com/documentation).
## ๐ Installation
To install Unsplash Image Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@hellokaton/unsplash-mcp-server):
### IDE Setup
**Cursor IDE**
```bash
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cursor --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"
```
**Windsurf**
```bash
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client windsurf --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"
```
**Cline**
```bash
npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cline --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"
```
### Manual Installation
```bash
# 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 `uv` is not in your system PATH, use an absolute path (e.g., `/path/to/uv`)
- `./server.py` should be modified to the actual location of your server script (can use absolute path or path relative to workspace)
```json
{
"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
```json
{
"tool": "search_photos",
"query": "mountain",
"per_page": 5,
"orientation": "landscape"
}
```
## ๐ Other Implementations
- Golang: [unsplash-mcp-server](https://github.com/douglarek/unsplash-mcp-server)
- Java: [unsplash-mcp-server](https://github.com/JavaProgrammerLB/unsplash-mcp-server)
## ๐ License
[MIT License](LICENSE)
## ๐ฌ Contact
- [Twitter/X](https://x.com/hellokaton)
- [GitHub Issues](https://github.com/hellokaton/unsplash-mcp-server/issues)