playbooks
Learn Rules MCPs Modes
AI Image Editor
Log in

Unsplash MCP server

Connects to Unsplash's API to enable photo searching with customizable filters, detailed image information retrieval, and random photo fetching for seamless imagery integration in conversations.
Back to servers
Provider
okooo5km
Release date
Mar 19, 2025
Language
Swift
Stats
8 stars
View on GitHub

The Unsplash MCP Server provides a Model Context Protocol implementation allowing Large Language Models (LLMs) to search and retrieve photos from Unsplash. This server enables integration with LLMs through tools like search_photos, get_photo, and random_photo to leverage Unsplash's extensive photo collection.

Features

  • Advanced Image Search: Search Unsplash's photo library with filters for keywords, colors, orientation, and more
  • Detailed Photo Information: Retrieve comprehensive details about specific photos
  • Random Photo Selection: Get random photos with customizable filtering options
  • Multiple Connection Modes: Supports both Standard I/O and Server-Sent Events (SSE)

Available Tools

search_photos

Search for photos on Unsplash with various parameters:

  • query (string, required): Search keyword
  • page (number, optional): Page number (1-based), default: 1
  • per_page (number, optional): Results per page (1-30), default: 10
  • order_by (string, optional): Sort method (relevant or latest), default: "relevant"
  • color (string, optional): Color filter (black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue)
  • 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 with filters:

  • count (number, optional): Number of photos to return (Default: 1; Max: 30)
  • collections (string, optional): Public collection ID('s), comma-separated if multiple
  • topics (string, optional): Public topic ID('s), comma-separated if multiple
  • username (string, optional): Limit selection to a specific user
  • query (string, optional): Limit selection to photos matching a search term
  • orientation (string, optional): Filter by photo orientation (landscape, portrait, squarish)
  • content_filter (string, optional): Limit results by content safety (low, high)
  • featured (boolean, optional): Limit selection to featured photos

Installation

Option 1: Download Pre-built Binary

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

macOS Installation (Apple Silicon)

# Download the arm64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-arm64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

macOS Installation (Intel)

# Download the x86_64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-x86_64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

Linux Installation (x86_64)

# Download the amd64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-amd64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

Windows Installation

  • Download the Windows AMD64 version
  • Extract the ZIP file
  • Move the unsplash-mcp-server.exe to a location in your PATH

Option 2: Build from Source

  1. Clone the repository:

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

  2. Build the project:

    # Using Make (recommended)
make

# Or using Go directly
go build -o unsplash-mcp-server

  3. Install the binary:

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

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

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

Configuration

Obtain an Unsplash API Access Key

  1. Go to the Unsplash Developers Portal
  2. Sign up or log in to your Unsplash account
  3. Register a new application
  4. Accept the API use and guidelines
  5. Fill in your application details
  6. Once registered, you'll receive your Access Key (Client ID)

Set Environment Variables

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

Configure for Claude.app

Add to your Claude settings:

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

Configure for Cursor

Add to your Cursor editor's settings.json:

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

Command Line Arguments

The server supports these command line arguments:

  • -h, --help: Display help information
  • -v, --version: Display the version number
  • -t, --transport <string>: Transport type (default: "stdio")
    • stdio: Standard input/output mode
    • sse: Server-Sent Events mode
  • -p, --port <int>: Port to use in SSE mode (default: 8080)

Example usage:

# Start server with default settings (stdio mode)
unsplash-mcp-server

# Start server in SSE mode on the default port
unsplash-mcp-server --transport sse

# Start server in SSE mode on a custom port
unsplash-mcp-server --transport sse --port 9090

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"
}

Example System Prompt

You can use this system prompt to help LLMs utilize the server effectively:

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

1. Search for photos using specific keywords, colors, or orientations:
   - Use the search_photos tool to find images on any topic
   - Filter by color or orientation as needed
   - You can page through results and control how many appear per page

2. Get detailed information about specific photos:
   - Use get_photo with a photo ID to retrieve comprehensive details
   - This includes EXIF data, location info, and photographer details

3. Fetch random photos with customizable filters:
   - Use random_photo tool to get surprise images based on criteria
   - Filter random selections by topic, collection, username, etc.

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later