Unsplash MCP Server

Fetch high-quality Unsplash photos via MCP with proper attribution (plain text + ready-to-embed HTML). Designed for LLMs that build content pages and need correctly credited images.

Features

• Search photos by keyword with filters (color, orientation)
• Random photos for variety in content
• Download tracking to stay compliant with Unsplash API guidelines
• Full attribution included for every photo:
  • attribution_text (plain text)
  • attribution_html (HTML with proper links)

Why this server?

Unsplash requires proper attribution when using their photos. This server makes it easy by returning attribution alongside every photo result, ready to paste into web pages.

Installation

Prerequisites

• Python 3.11+
• An Unsplash API Access Key

Quick start

git clone https://github.com/cevatkerim/unsplash-mcp.git  
cd unsplash-mcp  
  
python3 -m venv .venv  
source .venv/bin/activate  
  
pip install fastmcp httpx python-dotenv  
  
echo "UNSPLASH_ACCESS_KEY=your_key_here" > .env  
  
fastmcp run server.py  

Configuration

Claude Code (~/.claude.json 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

{  
  "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

{  
  "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 by keyword with optional filters:

• query (required)
• page (default: 1)
• per_page (default: 10, range 1–30)
• order_by (default: "relevant", or "latest")
• color (optional): black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue
• orientation (optional): landscape, portrait, squarish
• content_filter (default: "low", or "high")

Example:

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

get_random_photos

Get random photos (optionally filtered):

• query (optional)
• count (default: 1, range 1–30)
• orientation (optional)
• content_filter (default: "low" or "high")

Example:

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

track_download

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

• photo_id (required)

Example:

track_download("abc123xyz")  

Response format (high level)

Each photo includes image URLs plus attribution fields like:

• attribution_text: Photo by John Doe on Unsplash
• attribution_html: Photo by <a href="...">John Doe</a> on <a href="...">Unsplash</a>

Usage example

1. Search:

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

2. Render:

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

3. Track download (if you provide a download action):

download_url = track_download(photo.id)  

Notes on compliance

• Always include attribution (use attribution_html)
• Hotlink images using the returned URLs
• Track downloads using track_download() when users download images

License

MIT