Unsplash Mcp

Unsplash MCP Server

An MCP (Model Context Protocol) server for fetching photos from Unsplash with proper attribution. Designed for LLMs building content pages that need properly credited images.

Features

• Search Photos - Find photos by keyword with filters (color, orientation)
• Random Photos - Get random photos for variety in content
• Download Tracking - Compliant with Unsplash API guidelines
• Full Attribution - Every photo includes ready-to-use attribution text and HTML
• LLM-Optimized - Pre-formatted attribution strings for easy embedding

Why This Server?

Unsplash requires proper attribution when using their photos. This server makes it easy by including:

• attribution_text: Plain text like "Photo by John Doe on Unsplash"
• attribution_html: Full HTML with proper links for web pages

Photo by John Doe on Unsplash

Installation

Prerequisites

• Python 3.11+
• An Unsplash API access key (Get one here)

Quick Start

# Clone the repository
git clone https://github.com/cevatkerim/unsplash-mcp.git
cd unsplash-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install fastmcp httpx python-dotenv

# Set your API key
echo "UNSPLASH_ACCESS_KEY=your_key_here" > .env

# Run the server
fastmcp run server.py

Configuration

Claude Code

Add to your ~/.claude.json (user-level) or project .mcp.json:

{
  "mcpServers": {
    "unsplash": {
      "type": "stdio",
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "unsplash": {
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Windsurf / Cline

Add to your MCP configuration:

{
  "unsplash": {
    "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
    "args": ["run", "/path/to/unsplash-mcp/server.py"],
    "env": {
      "UNSPLASH_ACCESS_KEY": "your_access_key_here"
    }
  }
}

Tools

search_photos

Search for photos by keyword with optional filters.

Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Search keyword(s) | | page | int | 1 | Page number | | per_page | int | 10 | Results per page (1-30) | | order_by | string | "relevant" | Sort: "relevant" or "latest" | | color | string | null | Color filter (see below) | | orientation | string | null | "landscape", "portrait", "squarish" | | content_filter | string | "low" | Safety: "low" or "high" |

Color options: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue

Example:

search_photos("mountain sunset", per_page=5, orientation="landscape")

get_random_photos

Get random photos, optionally filtered by keyword.

Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | null | Optional keyword filter | | count | int | 1 | Number of photos (1-30) | | orientation | string | null | "landscape", "portrait", "squarish" | | content_filter | string | "low" | Safety: "low" or "high" |

Example:

get_random_photos(query="nature", count=3, orientation="landscape")

track_download

Track a photo download (required by Unsplash API guidelines).

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | photo_id | string | Photo ID from search results |

Example:

track_download("abc123xyz")

Response Format

Each photo includes:

{
    "id": "abc123",
    "description": "A beautiful mountain landscape",
    "alt_description": "snow-capped mountains under blue sky",
    "urls": {
        "raw": "https://images.unsplash.com/...",
        "full": "https://images.unsplash.com/...",
        "regular": "https://images.unsplash.com/...",  # Recommended for web
        "small": "https://images.unsplash.com/...",
        "thumb": "https://images.unsplash.com/..."
    },
    "width": 4000,
    "height": 3000,
    "color": "#a3c4f3",  # Dominant color for placeholders
    "blur_hash": "LKO2?U%2Tw=w...",  # For progressive loading

    # Attribution (REQUIRED when using the image)
    "photographer_name": "John Doe",
    "photographer_username": "johndoe",
    "photographer_url": "https://unsplash.com/@johndoe?utm_source=...",
    "photo_url": "https://unsplash.com/photos/abc123?utm_source=...",

    # Ready-to-use attribution
    "attribution_text": "Photo by John Doe on Unsplash",
    "attribution_html": "Photo by John Doe on Unsplash"
}

Usage Example

When an LLM builds a content page:

1. Search for relevant images:

`` photos = search_photos("coffee shop interior", per_page=5) ``

1. Select a photo and use it:

```html

{photo.attribution_html} ```

1. If offering download, track it:

`` download_url = track_download(photo.id) ``

Unsplash API Guidelines

This server helps you comply with Unsplash API guidelines:

1. Attribution - Always credit the photographer and Unsplash (use attribution_html)
2. Hotlinking - Use the provided URLs directly (enables view tracking)
3. Download tracking - Call track_download() when users download images

Rate Limits

• Demo mode: 50 requests/hour
• Production: 5,000 requests/hour (after approval)

License

MIT License - See [LICENSE](LICENSE) file.

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

Support

If you find this project useful, consider buying me a coffee!

Acknowledgments

• Unsplash for providing an amazing free photo API
• FastMCP for the MCP server framework

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cevatkerim
• Source: cevatkerim/unsplash-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.