Unsplash MCP Server

How to use

You connect the Unsplash MCP Server to your MCP client and start sending tool requests to search for photos, fetch detailed photo information, or retrieve random images. Use the tools to power image-based responses in your conversations or applications. Each tool returns data that you can present as image URLs, metadata, or EXIF information to users.

How to install

Prerequisites you need before installing: Go 1.20 or later, a working shell, and access to install or download binaries.

# Option 1: Download pre-built binaries
# macOS with Apple Silicon
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
xattr -d com.apple.quarantine unsplash-mcp-server
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# macOS with Intel
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
xattr -d com.apple.quarantine unsplash-mcp-server
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Linux x86_64
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
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

# Linux ARM64
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-arm64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

# Windows instructions are omitted here; use the appropriate binary and add it to PATH

If you prefer building from source, you can compile and run the server locally with Go.

# Clone the project
git clone https://github.com/okooo5km/unsplash-mcp-server-go.git
cd unsplash-mcp-server-go

# Build the project (Go 1.20+ required)
go build -o unsplash-mcp-server

# Install to user directory (no sudo required)
mkdir -p ~/.local/bin
cp unsplash-mcp-server ~/.local/bin/

# Ensure the binary is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

Configuration and usage notes

Set your Unsplash API access key as an environment variable before running the server to enable API requests.

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

Configure for client integrations

You can configure clients like Claude.app or Cursor to connect to the Unsplash MCP Server by specifying the server command and environment variable.

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

Command line options at a glance

You can start the server with different transport modes. In standard I/O mode, the server communicates through your process input and output. In SSE mode, you can connect via HTTP for web clients.

# Default: stdio mode
unsplash-mcp-server

# SSE mode on default port 8080
unsplash-mcp-server --transport sse

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

Examples and tips

The server exposes three main capabilities: search photos, fetch photo details, and get random photos. Use search_photos to find images by keyword with optional color and orientation filters, get_photo to retrieve detailed info about a specific photo, and random_photo to obtain one or more random images with optional filtering.

Security and maintenance notes

Keep your Unsplash API access key secure. Do not share keys in client-side code or public repositories. Rotate keys periodically and monitor usage for unusual activity.

search_photos

Searches Unsplash for photos matching a keyword with optional filters such as page, per_page, order_by, color, and orientation.

get_photo

Fetches detailed information about a specific photo by its ID, including EXIF data and photographer details.

random_photo

Returns one or more random photos with optional filters like collections, topics, username, query, orientation, content_filter, and featured.