unsplash-mcp

Purpose

unsplash-mcp is a server based on the Model Context Protocol (MCP) for fetching photos from Unsplash, with built-in standardized image attribution. It is designed for LLMs that need to provide images for content pages and correctly credit the sources.

Unsplash requires appropriate attribution when its photos are used. This server simplifies this process by generating ready-to-use attribution text and HTML for each photo, enabling LLMs to conveniently build content pages with correctly attributed images (in compliance with the Unsplash API Guidelines).

Main Capabilities

• Search Photos: Find photos by keyword, with support for filters (color, orientation).
• Random Photos: Get random photos to add diversity to content, and can also be filtered by keyword.
• Download Tracking: Complies with the Unsplash API Guidelines by tracking when users download images.
• Full Attribution: Each photo includes ready-to-use attribution text and HTML.
• LLM-Optimized: Provides preformatted attribution strings for easy embedding.

Specific tools include:

• search_photos: Search photos by keyword, with optional filters. Color options: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue.
• get_random_photos: Get random photos, optionally filtered by keyword.
• track_download: Track photo downloads (required by the Unsplash API Guidelines).

Usage

An Unsplash API access key is required.

Add the server to the configuration file (user-level ~/.claude.json or project-level .mcp.json）：

{
  "mcpServers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "unsplash-mcp"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Add to Cursor MCP settings: Add the above MCP configuration to Cursor's MCP settings.

Windsurf / Cline: Add the above MCP configuration to the corresponding MCP configuration.

Response Format and Usage Flow

Information included for each photo (the original text does not list the fields one by one, but mentions including urls.regular、alt_description、attribution_html、id , etc.).

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:<img src="{photo.urls.regular}" alt="{photo.alt_description}"> <p class="attribution">{photo.attribution_html}</p>
3. If providing a download, track it:download_url = track_download(photo.id)

Use Cases

• LLMs find and embed images for content pages.
• Need to automatically generate attribution text and HTML that meet Unsplash requirements for images.
• Need random images to increase content diversity.
• Need to comply with the Unsplash API Guidelines for download tracking.

Limitations

• Requires an Unsplash API access key.
• Rate limits: Demo mode is 50 requests/hour; Production mode is 5,000 requests/hour (after approval).
• Must comply with the Unsplash API Guidelines: use attribution_html to credit the photographer and Unsplash; use the provided URL directly (to enable view tracking); call track_download()when users download images.

Other Information

• License: MIT License (see the LICENSE file for details).
• Contributions welcome (submit a Pull Request).