cevatkerim/unsplash-mcp

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 <a href="https://unsplash.com/@johndoe">John Doe</a> on <a href="https://unsplash.com">Unsplash</a>

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 <a href=\"...\">John Doe</a> on <a href=\"...\">Unsplash</a>"
}

Usage Example

When an LLM builds a content page:

1. Search for relevant images:

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

2. Select a photo and use it:

   <img src="{photo.urls.regular}" alt="{photo.alt_description}">
   <p class="attribution">{photo.attribution_html}</p>
   

3. 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 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