unsplash-mcp

violent-madman/unsplash-mcp

3.1

If you are the rightful owner of unsplash-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Unsplash MCP Server is a user-friendly server that integrates with Unsplash's stock photo API, providing developers with easy access to high-quality images for web development projects.

Tools
4
Resources
0
Prompts
0

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 file for details.

Contributing

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

Support

Made with ❤️ for the Claude Code community