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.

search_unsplash_collections

Search for collections on Unsplash.

download_unsplash_media

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

download_unsplash_media_batch

Download multiple photos from Unsplash URLs in parallel.

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