# Unsplash MCP Server

MCP (Model Context Protocol) server that exposes [Unsplash](https://unsplash.com/) 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](https://unsplash.com/developers).

### 2. Configure your MCP client

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

```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

```bash
# 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