📌Overview

Purpose: To provide a server framework for searching and retrieving photos from Unsplash, specifically designed for interaction with large language models (LLMs).

Overview: The Unsplash MCP Server is a Swift implementation of a Model Context Protocol server, facilitating seamless access to Unsplash's extensive photo collection. It allows users to perform advanced searches, retrieve detailed photo information, and obtain random images, enhancing the usability of Unsplash in various applications.

Key Features:

Advanced Image Search: Enables users to search Unsplash's library with options for keyword relevance, color filters, orientation, and custom sorting and pagination.
Detailed Photo Information: Provides in-depth details such as EXIF data, location, and photographer information for specific photos.
Random Photo Selection: Offers flexibility in fetching random photos using filters like collections, topics, and orientation, along with content safety controls.

Unsplash MCP Server

A Model Context Protocol server that provides Unsplash photo search and retrieval capabilities. This Swift implementation of the server includes features like get_photo and random_photo.

✨ Features

Advanced Image Search: Search Unsplash's extensive photo library with filters for keyword relevance, color schemes, orientation options, and custom sorting.
Detailed Photo Information: Access comprehensive details about specific photos including EXIF data and photographer information.
Random Photo Selection: Retrieve random photos with flexible filtering options.

Available Tools

search_photos: Search for photos on Unsplash.
- query (string, required): Search keyword.
- page (number, optional): Page number (1-based; default: 1).
- perPage (number, optional): Results per page (1-30; default: 10).
- orderBy (string, optional): Sort method (relevant or latest; default: "relevant").
- color (string, optional): Color filter options.
- orientation (string, optional): Orientation filter (landscape, portrait, squarish).
get_photo: Get detailed information about a specific photo.
- photoId (string, required): The photo ID to retrieve.
random_photo: Get one or more random photos.
- count (number, optional): Number of photos to return (Default: 1; Max: 30).
- Additional optional filters: collections, topics, username, query, orientation, content_filter, featured.

Installation

Option 1: One-Line Installation (curl)

Install with the one-line installer:

curl -fsSL https://raw.githubusercontent.com/okooo5km/unsplash-mcp-server-swift/main/install.sh | bash

Option 2: Build from Source

Clone the repository:

git clone https://github.com/okooo5km/unsplash-mcp-server-swift.git
cd unsplash-mcp-server-swift

Build the project:
```
swift build -c release
```

Install the binary:

mkdir -p ~/.local/bin
cp $(swift build -c release --show-bin-path)/unsplash-mcp-server ~/.local/bin/

Make sure ~/.local/bin is in your PATH by updating your shell configuration file:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

Configuration

Environment Variables

Set the Unsplash API access key in your environment:

export UNSPLASH_ACCESS_KEY="your-access-key-here"

Obtain an Unsplash API Access Key

Go to the Unsplash Developers Portal.
Sign up or log in to your Unsplash account.
Register a new application.
Once registered, you'll receive your Access Key.

Configure for Claude.app

Add to your Claude settings:

"mcpServers": {
  "unsplash": {
    "command": "unsplash-mcp-server"
  }
}

Configure for Cursor

Add to your Cursor editor's settings.json:

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "${YOUR_ACCESS_KEY}"
      }
    }
  }
}

Development Requirements

Swift 6.0 or later
macOS 14.0 or later
Unsplash API access key
MCP Swift SDK 0.2.0 or later

Version History

Check GitHub Releases for version history and changelog.

☕️ Support the Project

If you find this project useful, consider supporting its development by starring the project on GitHub, reporting bugs, or contributing through pull requests.

License

The Unsplash MCP Server is licensed under the MIT License. You are free to use, modify, and distribute the software under this license.