Unsplash MCP Server

MCP (Model Context Protocol) server that exposes Unsplash photo and collection search as tools for AI agents.

Search and retrieve royalty-free photos — all from within your MCP-compatible client.

Features

• 🖼️ Photo Search — high-quality photos with filters for orientation, color, content safety, and more
• 📁 Collection Search — discover curated photo collections by keyword
• 📥 Download — download single or batch photos to local files
• 🔒 Content Filter — optional stricter filtering for younger audiences
• 📄 Pagination — full control over page size and page number

Quick Start

1. Get an Unsplash Access Key

Sign up for a free API key at unsplash.com/developers.

2. Configure your MCP client

Add the following to your MCP client configuration (e.g. mcp_config.json):

{
  "unsplash": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/spideryzarc/unsplash-mcp",
      "unsplash-mcp"
    ],
    "env": {
      "UNSPLASH_ACCESS_KEY": "YOUR_ACCESS_KEY_HERE"
    }
  }
}

Replace YOUR_ACCESS_KEY_HERE with your actual Unsplash Access Key.

That's it! The server will be installed and started automatically by uvx.

Available Tools

search_unsplash_photos

Search for photos on Unsplash.

Parameter	Type	Default	Description
query	string	(required)	Search terms
orientation	string	—	landscape, portrait, squarish
color	string	—	e.g. black_and_white, red, blue
content_filter	string	"low"	low or high
order_by	string	"relevant"	relevant or latest
collections	string	—	Comma-separated collection IDs
page	number	1	Page number
per_page	number	10	Results per page (1–30)

search_unsplash_collections

Search for collections on Unsplash.

Parameter	Type	Default	Description
query	string	(required)	Search terms
page	number	1	Page number
per_page	number	10	Results per page (1–30)

download_unsplash_media

Download a single photo from an Unsplash URL to a local file.

Parameter	Type	Description
url	string	The Unsplash photo URL (e.g. urls.regular)
dest_path	string	Absolute local file path to save the file

download_unsplash_media_batch

Download multiple photos from Unsplash URLs in parallel.

Parameter	Type	Description
files	array	List of objects with url and dest_path per file

Development

# Clone and install locally
git clone https://github.com/spideryzarc/unsplash-mcp.git
cd unsplash-mcp

# Create a virtual environment (optional)
uv venv && source .venv/bin/activate

# Install in editable mode
uv pip install -e .

# Run the server directly
UNSPLASH_ACCESS_KEY="your_key" unsplash-mcp

License

MIT