📌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 Go implementation offers tools like search_photos, get_photo, and random_photo to enable LLMs to search, retrieve, and get random photos from Unsplash's extensive collection.

✨ Features

Advanced Image Search: Search Unsplash's photo library with filters for:
- Keyword relevance
- Color schemes
- Orientation options
- Custom sorting and pagination
Detailed Photo Information: Retrieve comprehensive details about photos, including EXIF data, location, and photographer info.
Random Photo Selection: Obtain random photos with flexible filtering.
Multiple Connection Modes:
- Standard I/O mode for direct LLM integration
- Server-Sent Events (SSE) mode for web-based connections

Available Tools

search_photos - Search photos on Unsplash
Parameters:
- query (string, required): Search keyword
- page (number, optional, default: 1): Page number (1-based)
- per_page (number, optional, default: 10, max 30): Results per page
- order_by (string, optional, default: "relevant"): Sort by "relevant" or "latest"
- color (string, optional): Filter by color (e.g., black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue)
- orientation (string, optional): Filter by orientation (landscape, portrait, squarish)
get_photo - Get details of a specific photo
- photoId (string, required): Photo ID
random_photo - Get one or more random photos
Parameters:
- count (number, optional, default: 1, max 30)
- collections (string, optional): Public collection ID(s), comma-separated
- topics (string, optional): Public topic ID(s), comma-separated
- username (string, optional): Limit by user
- query (string, optional): Filter by search term
- orientation (string, optional): landscape, portrait, or squarish
- content_filter (string, optional): low or high content safety
- featured (boolean, optional): Limit to featured photos

Installation

Option 1: Download Pre-built Binary

Download the latest pre-built binary from the GitHub Releases page.

macOS Installation

Apple Silicon (M1/M2/M3), Intel, or Universal binaries available.
Download, unzip, make executable, and move to ~/.local/bin/.
Remove quarantine attribute on macOS to avoid warnings.

Linux Installation

Versions available for x86_64 and ARM64.
Download, extract, make executable, and move to ~/.local/bin/.

Windows Installation

Versions available for AMD64 and ARM64.
Download, extract, and move the executable to a location in your PATH.

Ensure the installation directory is in your PATH:

macOS/Linux: Add export PATH="$HOME/.local/bin:$PATH" to your shell config (e.g., .bashrc, .zshrc).
Windows: Add the directory to your system PATH via System Properties.

Option 2: Build from Source

Clone the repository:

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

Build the project:

Using Make (recommended):

make           # Build for current platform
make build-all # Build for all supported platforms

Or using Go directly:

go build -o unsplash-mcp-server

Install the binary:

mkdir -p ~/.local/bin
cp unsplash-mcp-server ~/.local/bin/

Add to PATH if needed:

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

Configuration

Environment Variables

Set your Unsplash API Access Key in the environment:

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

You can obtain an access key by registering an application on the Unsplash Developers Portal.

Integration with Clients

Claude.app

Add to Claude settings:

"mcpServers": {
  "unsplash": {
    "command": "unsplash-mcp-server",
    "env": {
      "UNSPLASH_ACCESS_KEY": "your-access-key-here"
    }
  }
}

Cursor

Add to Cursor editor's settings.json:

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your-access-key-here"
      }
    }
  }
}

Chatwise

Note: When adding environment variables in Chatwise, do not wrap the value in quotes.

Command Line Arguments

-h, --help: Show help information
-v, --version: Show version number
-t, --transport <string>: Transport type (stdio or sse, default: stdio)
-p, --port <int>: Port for SSE mode (default: 8080)

Examples:

unsplash-mcp-server --help
unsplash-mcp-server --version
unsplash-mcp-server                      # Start in stdio mode
unsplash-mcp-server --transport sse     # Start SSE mode on default port 8080
unsplash-mcp-server --transport sse --port 9090

In SSE mode, the server is accessible via HTTP, suitable for web clients. StdIO mode is ideal for direct LLM integration.

Example System Prompt

You have access to Unsplash photo search tools through MCP. You can:

1. Search for photos with keywords, colors, or orientations using the search_photos tool.  
2. Get detailed photo information using get_photo with a photo ID.  
3. Fetch random photos with filters using random_photo.

When the user asks for images, use these tools to find relevant Unsplash photos.
Include photo URLs in your responses for users to view.

Development Requirements

Go 1.20 or later
Unsplash API access key
MCP Go SDK 0.19.0 or later

Usage Examples

Searching for Photos

{
  "query": "mountain landscape",
  "per_page": 5,
  "color": "blue",
  "orientation": "landscape"
}

Getting Photo Details

{
  "photoId": "Dwu85P9SOIk"
}

Getting Random Photos

{
  "count": 3,
  "query": "coffee",
  "orientation": "portrait"
}

Version History

See GitHub Releases for version history and changelog.

☕️ Support the Project

If you find this project useful, please consider supporting development:

Star the project on GitHub
Report bugs or suggest features
Submit pull requests
Support via Buy Me A Coffee at: https://buymeacoffee.com/okooo5km

License

unsplash-mcp-server-go is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License. See the LICENSE file in the repository for details.

unsplash-mcp-server-swift