# Unsplash MCP

> Unsplash MCP connects your AI client directly to Unsplash’s massive library of high-resolution photos and curated collections. Your agent can search by natural language prompts, retrieve photo IDs and direct links, pull entire thematic collections, or even list public portfolios from specific photographers. Stop browsing web pages; let your AI handle the visual asset retrieval automatically.

## Overview
- **Category:** design-creative
- **Price:** Free
- **Tags:** photography, asset-retrieval, high-resolution, visual-search, media-library, creative-assets

## Description

Need stunning visuals for a project, but hate clicking through dozens of stock sites? This MCP connects your AI client to Unsplash's full photography ecosystem. You get autonomous control over discovering and pulling high-res images right inside your chat interface.

Instead of spending time on the Unsplash homepage manually searching or downloading assets, you give a plain language prompt to your agent—like 'Give me three minimalist shots of coffee shops.' Your AI client then uses this MCP to find those exact photos, pull the direct links, and provide all the metadata needed for proper credit. It’s like having a dedicated visual research assistant that never gets tired.

When you connect this through Vinkius, your agent can handle complex tasks instantly. You can ask it to search thematic collections by keyword or even pluck out a random high-res image when prototyping a layout. This means less time searching and more time building. It's the difference between browsing an index and getting the finished asset ready for production.

## Tools

### list_collection_photos
Lists every photo contained within an existing Unsplash collection ID.

### get_collection_details
Retrieves all information about a specific, named photo collection.

### get_photo_details
Pulls comprehensive data for any single Unsplash photo.

### get_photographer_photos
Lists every image uploaded by a specific, named user account on Unsplash.

### list_latest_photos
Retrieves a list of the most recently published photos from the main feed.

### list_editorial_topics
Shows available, curated topics like 'Nature' or 'Architecture' that you can search within.

### get_random_photo
Fetches a random high-resolution photo, optionally narrowed by a specific query.

### search_collections
Searches for entire curated photo collections based on keywords like 'Nature' or 'Industrial'.

### search_photos
Performs a broad search across Unsplash, returning IDs and URLs of free high-resolution photos.

### search_photographers
Finds specific photographers or artists by their name or username on Unsplash.

## Prompt Examples

**Prompt:** 
```
Search for 3 high resolution images containing 'cyberpunk city' aesthetics and provide their URLs natively in your response.
```

**Response:** 
```
I've tapped the search engine: I found three gorgeous neon-lit cyberpunk style captures. [Image 1: Tokyo Nights API URL], [Image 2: Neon Reflection API URL], [Image 3: Rainy Alley API URL]. Photographers are mentioned below for proper attribution.
```

**Prompt:** 
```
Grab a random photo matching 'coffee desk concept' to help me prototype a blog layout.
```

**Response:** 
```
Random request executed. I returned Photo ID yX45p, showcasing a minimalist white desk with an espresso shot, shot natively by James L. [Here is the Raw Image URL] to plug into your `src` tag.
```

**Prompt:** 
```
I need to see what's trending. Quickly gather the 10 most recently published latest photos off the main feed.
```

**Response:** 
```
I've hit the latest unformatted feed natively. The top fresh photos display a significant trend in abstract landscapes and minimalist tech setups from users across Europe. Returning a list of their IDs alongside URLs right now.
```

## Capabilities

### Find photos using keywords
You can search Unsplash’s entire library to find high-resolution images that match specific concepts or subjects.

### Retrieve photo details and links
The MCP pulls deep data on any given image, including its ID, resolution properties, and direct hotlinks for use in web projects.

### Browse curated groups of photos
You can request specific themed collections or audit existing photo sets by their unique IDs.

### Get random inspiration shots
If you need a placeholder image for testing, your agent can retrieve a completely random high-resolution visual instantly.

### Track specific artists' work
You can list all the public photos uploaded by a particular photographer or user ID.

### List trending and new content
The agent retrieves lists of the most recently published images or current editorial topics to see what's popular now.

## Use Cases

### Building a Portfolio Site
A designer needs 15 images for a client's mood board. Instead of manually searching Unsplash repeatedly, they prompt their agent to use `search_collections` and then run `list_collection_photos` on the best result. The agent returns all 15 assets with links in one go.

### Testing a Landing Page Layout
A frontend developer needs background images for rapid prototyping. They simply tell their AI client to use `get_random_photo` multiple times, which instantly provides diverse, high-res assets without the friction of leaving their IDE.

### Writing a Travel Blog
A blogger is writing about Italian architecture. They prompt their agent with 'Renaissance buildings' and the MCP uses `search_photos` to find relevant images, providing direct links for the blog post's embedded visuals.

### Researching Brand Identity
A marketing manager needs to see what a competitor might look like. They use `search_photographers` to locate similar accounts and then run `get_photographer_photos` to audit the public style of specific artists.

## Benefits

- Save time by eliminating manual browsing. Instead of opening the Unsplash site and clicking through pages to find images, you simply tell your agent what you need, and it runs a targeted search using `search_photos`.
- Get structured data, not just pictures. The MCP retrieves photo IDs, direct URLs, and metadata. This means your AI client can plug assets directly into code or reports without manual copy-pasting.
- Maintain visual consistency across projects. You don't have to settle for random images; you can use `search_collections` to pull entire thematic bundles of visuals that share a consistent look and feel.
- Prototype faster with placeholder imagery. When building a new layout, the MCP lets your agent run `get_random_photo`, instantly giving you realistic assets so you don't have to stop development to source images.
- Track creative sources reliably. Use `search_photographers` or `get_photographer_photos` to find and catalogue work from specific artists, ensuring proper attribution right out of the gate.

## How It Works

The bottom line is that you give an instruction in natural language, and your MCP handles all the complicated API calls to get you exactly what you need.

1. First, manually subscribe to this MCP instance within Vinkius and provide your Personal Unsplash Developer App Access Key.
2. Next, trigger the photo search or collection audit by giving a specific semantic constraint prompt to your AI client (like Claude or Cursor).
3. Finally, your agent executes the necessary tools, retrieves the direct asset links and metadata, and presents them directly in your chat window.

## Frequently Asked Questions

**How do I use the search_photos tool with the Unsplash MCP?**
You ask your agent to run `search_photos` and provide descriptive keywords. Your agent then uses these tools to return IDs, URLs, and photographer information for free high-resolution images.

**Does the Unsplash MCP help me find a specific collection?**
Yes. You can use `search_collections` by keyword (e.g., 'Nature') or, if you have an ID, use `get_collection_details` to pull all information on it.

**What is the difference between search_photos and get_random_photo?**
Use `search_photos` when you need results based on specific keywords or themes. Use `get_random_photo` when you just need an immediate, random high-res placeholder to test a layout.

**Can I track the work of one photographer using Unsplash MCP?**
Absolutely. You use the `search_photographers` tool to find their account, and then run `get_photographer_photos` to list every public picture they've uploaded.

**Is the data from the Unsplash MCP always free to use?**
The MCP retrieves links to high-resolution photos that are available under Unsplash’s licensing terms, and it provides the necessary metadata for proper attribution.