Unsplash MCP Server

A Model Context Protocol (MCP) server that enables fetching and downloading images from Unsplash. This server integrates with OpenCode to provide tools for searching, retrieving, and saving Unsplash photos.

Features

• 🔍 Search Photos: Search Unsplash by query with filters for orientation, color, and ordering
• 🔗 Get Photo URL: Get direct image URLs from photo IDs (recommended for downloading)
• 📥 Download Photos: Download images to a specified directory with optional resizing
• 🎲 Random Photos: Get random photos from Unsplash with optional filters
• 📐 List Photo Sizes: Get available image sizes and URLs for any photo

Setup

Install dependencies

cd unsplash-mcp
pip install -r requirements.txt

Set Up Unsplash API Key

1. Go to Unsplash Developers
2. Sign up or log in
3. Create a new application
4. Copy your Access Key

Add to OpenCode config (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unsplash-mcp": {
      "type": "local",
      "command": ["python", "/absolute/path/to/server.py"],
      "enabled": true,
      "environment": {
        "UNSPLASH_ACCESS_KEY": "your_key_here"
      }
    }
  }
}

Usage

search_photos

Search photos. Each result includes image_url (direct image URL).

Search for "nature" photos, per_page=10, orientation="landscape"

Returns:

{
  "results": [
    {
      "id": "photo_123",
      "description": "A beautiful mountain",
      "image_url": "https://images.unsplash.com/photo-xxx...",
      "photographer": {"name": "John Doe"}
    }
  ]
}

download_photo

Download image to directory. Use image_url from search results.

Download image to ./`directory` with width=1920, quality=90

Workflow Examples

Simple (recommended):

1. search_photos(query="cats") → Get image_url from results
2. download_photo(photo_url="...", directory="./images")

Advanced (custom dimensions):

1. search_photos(query="sunset")
2. get_photo_download_url(photo_id="xxx", size="raw") → Get recommended_url
3. download_photo(photo_url="...", directory="./images", width=1920, height=1080)

Links

• Unsplash API Docs
• OpenCode MCP Docs