Unsplash MCP Server

An easy-to-use MCP server that provides seamless access to Unsplash's stock photo API for Claude Code users. Perfect for developers who need high-quality stock images during website development.

Features

• 🔍 Search Images: Find stock photos by keyword with filters
• 🎲 Random Images: Get random high-quality images
• 📋 Image Details: Retrieve complete metadata and attribution
• 🖼️ Optimized URLs: Generate properly sized image URLs for web use
• 🚀 Easy Installation: One command setup with Claude Code
• ⚡ Fast: Built with TypeScript and optimized for performance

Quick Start

1. Get Your Unsplash Access Key

1. Go to Unsplash Developers
2. Register for a free account
3. Create a new application
4. Copy your Access Key (you won't need the Secret Key)

2. Set Environment Variable

export UNSPLASH_ACCESS_KEY="your_access_key_here"

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

3. Install with Claude Code

claude mcp add unsplash npx @violent-madman/unsplash-mcp@latest

That's it! 🎉

Available Tools

search_images

Search Unsplash for stock images with filters.

// Example usage in Claude Code:
search_images({
  query: "mountain landscape",
  per_page: 10,
  orientation: "landscape",
  color: "blue"
})

Parameters:

• query (required): Search keywords
• page: Page number (default: 1)
• per_page: Images per page, 1-30 (default: 10)
• orientation: "landscape", "portrait", or "squarish"
• color: "black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue"
• content_filter: "low" or "high" (default: "low")

get_random_image

Get random high-quality images with optional filters.

get_random_image({
  count: 3,
  orientation: "portrait",
  query: "nature"
})

Parameters:

• count: Number of images, 1-30 (default: 1)
• collections: Comma-separated collection IDs
• topics: Comma-separated topic IDs
• username: Filter by photographer
• query: Keywords to filter random images
• orientation: "landscape", "portrait", or "squarish"
• content_filter: "low" or "high" (default: "low")

get_image_details

Get complete metadata for a specific image.

get_image_details({
  photo_id: "abc123xyz"
})

get_image_url

Generate optimized image URLs with custom dimensions.

get_image_url({
  photo_id: "abc123xyz",
  width: 800,
  height: 600,
  quality: 90,
  fit: "crop"
})

Parameters:

• photo_id (required): Unsplash photo ID
• width: Desired width in pixels
• height: Desired height in pixels
• quality: Image quality, 1-100 (default: 80)
• fit: "crop", "clip", or "scale" (default: "crop")

Rate Limits

• Demo Mode: 50 requests/hour (initial)
• Production Mode: 5000 requests/hour (after approval)

Attribution

All images from Unsplash require proper attribution. This MCP server automatically generates the correct attribution text for each image. Always include this in your projects:

Photo by [Photographer Name] on Unsplash (image_url)

Development

Local Setup

git clone https://github.com/violent-madman/unsplash-mcp.git
cd unsplash-mcp
npm install
export UNSPLASH_ACCESS_KEY="your_key"
npm run dev

Build

npm run build

Test

npm test

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests.

Support

• 🐛 Report issues: GitHub Issues
• 📚 Unsplash API: Official Documentation
• 🔧 MCP Protocol: Model Context Protocol

Made with ❤️ for the Claude Code community