🖼️ Unsplash Smart MCP Server

Empower your AI agents with stunning visuals, zero hassle.

A powerful FastMCP server that enables AI agents to seamlessly search, recommend, and deliver professional stock photos from Unsplash with intelligent context awareness and automated attribution management.

🚀 Why Choose This Unsplash Integration

In the landscape of visual content integration, our Unsplash Smart MCP Server stands out as the definitive solution for AI-powered image acquisition:

🧠 AI-Agent Optimized: Purpose-built for AI agents like Claude in Cursor, streamlining image requests with natural language
🔍 Context-Aware Image Selection: Interprets vague requests intelligently, delivering relevant images even from abstract prompts
⚡ Single Tool Efficiency: Eliminates tool spam with a unified stock_photo tool that handles the entire image workflow
📊 Resource Optimization: URL-first approach conserves bandwidth and storage while maintaining flexibility
✅ Automatic Attribution: Built-in compliance with Unsplash's Terms of Service with zero developer effort
📁 Project-Aware Organization: Intelligently organizes images based on your project structure (Next.js, React, Vue, etc.)
🧩 Seamless Integration: Designed for minimal setup and maximum compatibility with your existing workflow

✨ Features Beyond Comparison

For AI Agent Developers

Smart Contextual Search: Find the perfect image through natural language requests
Automatic Subject Selection: AI determines optimal image subjects from your purpose description
Intent-Driven Results: Get images that match not just keywords, but the underlying intent
Seamless Agent Integration: Works out-of-the-box with Claude in Cursor and other MCP-compatible agents

For Project Efficiency

Two-Step Workflow: Get URLs for controlled downloads, avoiding permission issues and unnecessary storage
Project-Aware File Management: Auto-organizes images based on framework conventions
Intelligent Directory Creation: Creates appropriate folder structures based on your project type
Progressive Enhancement: Works with any project size, from quick prototypes to enterprise applications

For Compliance Peace of Mind

Complete Attribution Management:
- Local attribution database tracks all image usage
- Automatic embedding of photographer metadata in images (EXIF, IPTC, XMP)
- One-click generation of attribution pages in multiple formats
- Comprehensive API for attribution data

🛠️ Installation

Prerequisites

Node.js 18.x or higher
An Unsplash API access key (get one here)

Local Installation (Recommended)

Clone the repository:

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

Install dependencies:

npm install

Configure your Cursor MCP settings:
- macOS: Edit ~/.cursor/mcp.json
- Windows: Edit %USERPROFILE%\.cursor\mcp.json
- Linux: Edit ~/.cursor/mcp.json
Add the following configuration:

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/absolute/path/to/unsplash-smart-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

Replace:
- /absolute/path/to/unsplash-smart-mcp-server with the actual path where you cloned the repo
- your_api_key_here with your Unsplash API key
Save the file and restart Cursor.

Important: Unlike many MCP servers, this server requires direct process piping and cannot be accessed via TCP ports or through npm directly due to how it handles FastMCP's I/O interactions. The local installation method is the most reliable approach.

Cursor CLI Alternative

If you prefer using Cursor's CLI:

claude mcp add unsplash npx tsx /path/to/unsplash-smart-mcp-server/src/server.ts --cwd /path/to/unsplash-smart-mcp-server
claude mcp config set unsplash UNSPLASH_ACCESS_KEY=your_api_key_here

Replace the paths and API key with your actual values.

Via Docker (Most Reliable Method)

Clone the repository:

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

Create a docker-compose.yml file:

services:
  unsplash-mcp:
    build: .
    image: unsplash-mcp-server
    restart: always
    stdin_open: true
    tty: true
    environment:
      - UNSPLASH_ACCESS_KEY=your_api_key_here

Build and start the container:

docker-compose up -d

Configure your Cursor MCP settings:
- macOS: Edit ~/.cursor/mcp.json
- Windows: Edit %USERPROFILE%\.cursor\mcp.json
- Linux: Edit ~/.cursor/mcp.json
Add the following configuration:

{
  "servers": {
    "unsplash": {
      "command": "docker",
      "args": ["exec", "-i", "unsplash-mcp-unsplash-mcp-1", "tsx", "src/server.ts"],
      "env": {}
    }
  }
}

Save the file and restart Cursor.

This setup will:

Start the server automatically when Docker starts
Restart the server if it crashes
Run in the background without terminal windows
Provide a reliable connection to Cursor

Via Smithery (Cloud Deployment)

If you prefer cloud deployment, you can use Smithery:

Install the server in Cursor via Smithery:

npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here

Alternatively, you can log in to Smithery.ai and deploy it through their web interface.

Note for Windows users: Smithery deployment includes special handling for Windows compatibility.

For detailed instructions and troubleshooting, see the Smithery Deployment Guide.

🧩 Integration with AI Agents

Step-by-Step Guide for Claude in Cursor

Our Unsplash Smart MCP Server is designed to make image acquisition through AI agents effortless and intuitive:

Initiate a request: Simply ask Claude for an image in natural language
AI interpretation: Claude understands your needs and calls the stock_photo tool with optimized parameters
Smart image selection: The server interprets context and finds the most relevant images
Presentation of options: Claude presents you with the best matches and download commands
Seamless download: Execute the suggested commands to place images exactly where you need them
Automatic attribution: All attribution data is stored and can be accessed whenever needed

This process eliminates the traditional workflow of:

~~Searching Unsplash manually~~
~~Scrolling through hundreds of results~~
~~Downloading images to random locations~~
~~Moving files to the correct project folders~~
~~Manually tracking attribution data~~
~~Creating attribution pages~~

Example Prompts for AI Agents

Ask Claude in Cursor for images using natural language prompts like these:

"Find a professional image for a tech startup landing page hero section"

🪟 Windows Compatibility

If you're using Windows and experiencing the "Client closed" error when running the MCP server in Cursor, follow these special configuration steps:

Windows-specific MCP Configuration

Create a file named mcp.json in your .cursor directory (typically at %USERPROFILE%\.cursor\mcp.json) with one of these configurations:

Option 1: Direct Node Execution (Recommended)

{
  "mcpServers": {
    "stock_photo": {
      "command": "node",
      "args": ["./node_modules/.bin/tsx", "path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      },
      "shell": false
    }
  }
}

Option 2: PowerShell Approach

{
  "mcpServers": {
    "stock_photo": {
      "command": "powershell",
      "args": ["-Command", "npx tsx path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

For complete documentation on Windows compatibility, see Windows Compatibility Guide.

🛠️ API Reference

URL-First Approach: The Smart Choice

Our architecture uses a URL-first approach rather than direct image embedding for several critical reasons:

Storage Efficiency: Prevents AI agents from unnecessarily storing large binary data in their context
Bandwidth Conservation: Reduces data transfer between services, improving response times
Placement Flexibility: Allows developers to download images exactly where they're needed
Permission Management: Avoids filesystem permission issues in restricted environments
Workflow Integration: Seamlessly integrates with existing development pipelines

This strategy enables AI agents to intelligently suggest the optimal download location based on project context, without being constrained by their own environment limitations.

Minimizing Tool Spam and API Calls

Unlike other solutions that require multiple tool calls for searching, filtering, downloading, and attributing images, our server:

Unifies the entire image workflow into a single stock_photo tool
Optimizes result retrieval by requesting more images upfront to enable better filtering
Eliminates ping-pong interactions between the agent and services
Reduces agent token usage by streamlining request and response formats

This design significantly reduces the number of API calls and tool invocations, leading to faster results and lower operational costs.

🔄 Automatic Attribution and Compliance

Unsplash Terms of Service: Effortless Compliance

Using images from Unsplash requires adherence to their Terms of Service. Our server handles this automatically:

Attribution Data Capture: Every image download automatically stores photographer information
Metadata Embedding: Photographer details are embedded directly into image files
Attribution Database: A local database maintains a record of all image usage
Attribution Generators: Built-in tools create HTML and React attribution components
API Access: Simple endpoints to retrieve attribution data for any project

By using our Unsplash Smart MCP Server, you are automatically compliant with Unsplash's requirements without any additional effort.

Attribution Management System

The server includes a comprehensive attribution management system:

// Retrieve attribution data for your project
const attributions = await fetch('http://localhost:3000/api/unsplash', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    method: 'get_attributions',
    params: {
      format: 'json',  // Options: json, html, react
      projectPath: '/path/to/your/project'
    }
  })
}).then(res => res.json());

// attributions contains complete data about every image used

The API can generate three types of attribution files:

JSON: Structured data for custom implementations
HTML: Ready-to-use HTML page for website footer or credits section
React: Drop-in React component for modern web applications

💼 Developer Workflow Integration

Real-World Use Cases

Our Unsplash Smart MCP Server seamlessly integrates into your development workflow:

UI Development

Instantly populate mockups with relevant placeholder images
Maintain consistent image dimensions across components
Organize images logically within your project structure

Documentation

Enhance technical documentation with explanatory visuals
Create visually appealing tutorials and guides
Maintain proper attribution for all visual assets

Content Creation

Quickly find images for blog posts and articles
Generate visuals for social media content
Access consistent imagery for product marketing

Application Development

Populate e-commerce sites with product imagery
Create visually rich user experiences
Maintain separate image collections for different sections

Framework-Specific Organization

Images are automatically organized based on your project type:

Framework	Default Image Path	Alternate Paths
Next.js	`/public/images/`	`/public/assets/images/`
React	`/src/assets/images/`	`/assets/images/`
Vue	`/src/assets/images/`	`/public/images/`
Angular	`/src/assets/images/`	`/assets/images/`
Generic	`/assets/images/`	`~/Downloads/stock-photos/`

🥇 Competitive Differentiation

Why Choose Our Unsplash Integration?

Feature	Unsplash Smart MCP Server	Alternatives
AI Agent Integration	✅ Purpose-built for AI agent workflow	❌ Typically requires manual parameter setting
Context Awareness	✅ Interprets vague requests intelligently	❌ Relies on exact keyword matching
Tool Efficiency	✅ Single tool handles entire workflow	❌ Often requires multiple separate tools
Attribution Management	✅ Comprehensive system with multiple formats	❌ Manual tracking or basic text output
Project Organization	✅ Framework-aware folder structures	❌ Generic downloads to a single location
Installation Complexity	✅ Simple one-line command	❌ Often requires multiple configuration steps
Response Format	✅ AI-optimized with relevant context	❌ Generic JSON requiring further processing
Download Flexibility	✅ URL-first with intelligent suggestions	❌ Either direct downloads or just URLs

⚙️ Configuration

Environment Variables

Variable	Description	Default
`UNSPLASH_ACCESS_KEY`	Your Unsplash API access key	-
`PORT`	Port for the server to listen on	`3000`
`HOST`	Host for the server	`localhost`
`ATTRIBUTION_DB_PATH`	Path to store attribution database	`~/.unsplash-mcp`

Tool Parameters

stock_photo

Parameter	Type	Description	Default
`query`	string	What to search for (AI will choose if not specified)	-
`purpose`	string	Where the image will be used (e.g., hero, background)	-
`count`	number	Number of images to return	`1`
`orientation`	string	Preferred orientation (any, landscape, portrait, square)	`any`
`width`	number	Target width in pixels	-
`height`	number	Target height in pixels	-
`minWidth`	number	Minimum width for filtering results	-
`minHeight`	number	Minimum height for filtering results	-
`outputDir`	string	Directory to save photos	`~/Downloads/stock-photos`
`projectType`	string	Project type for folder structure (next, react, vue, angular)	-
`category`	string	Category for organizing images (e.g., heroes, backgrounds)	-
`downloadMode`	string	Whether to download images or return URLs	`urls_only`

get_attributions

Parameter	Type	Description	Default
`format`	string	Output format (json, html, react)	`json`
`projectPath`	string	Filter attributions to a specific project path	-
`outputPath`	string	Where to save attribution files	-

🔧 Troubleshooting

Common Issues and Solutions

Issue	Solution
Connection Refused	Ensure the server is running on the configured port
Authentication Error	Verify your Unsplash API key is correctly set
No Images Found	Try broader search terms or check your search query
Download Permission Issues	Use `downloadMode: 'urls_only'` and manual download commands
Docker Container Exits Prematurely	Ensure you're using `CMD ["npm", "start"]` in your Dockerfile instead of directly running the TypeScript file with tsx. This ensures the server stays running in a Docker environment.
Timeout Errors	The default MCP timeout is 60 seconds, which may be insufficient for downloading larger images or processing multiple images. For image-heavy operations: 1) Process fewer images per request, 2) Use smaller image dimensions, 3) Consider using `urls_only` mode instead of auto-download, 4) Check network connectivity
Attribution Not Found	Verify the image was downloaded through the MCP server
Unhandled MCP Errors	If you see `"McpError: MCP error -32001: Request timed out"` errors, your request is likely taking too long. Break it into smaller operations or use the URLs-only approach

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Workflow

Clone the repository
Install dependencies with npm install
Create a .env file with your Unsplash API key
Run in development mode with npm run dev
Run tests with npm test

🗺️ Roadmap

Here's what we're planning for future releases:

Image Editing Capabilities: Basic resizing, cropping, and adjustment tools
Advanced Search Filters: More granular control over image selection
Batch Processing: Handle multiple image requests efficiently
Custom Collections: Save and manage groups of images for projects
Team Collaboration: Share attribution and image collections
Usage Analytics: Track image usage across projects
Additional Image Sources: Integration with other stock photo providers
Improved Timeout Handling: Enhanced timeout configuration and recovery mechanisms

📄 License

MIT License

📚 Attribution Requirements

When using images from Unsplash, you must comply with the Unsplash License:

Attribution is not required but appreciated
You cannot sell unaltered copies of the photos
You cannot compile photos from Unsplash to create a competing service

Our server's attribution system makes it easy to provide proper credit to photographers.

📞 Contact

For issues or questions, please open an issue on GitHub.

🧰 Development and Testing

Running the Server Locally

# Clone the repository
git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

# Install dependencies
npm install

# Set up your environment variables
cp .env.example .env
# Edit .env to add your UNSPLASH_ACCESS_KEY

# Start the development server
npm run dev

Testing

The package includes a comprehensive test suite:

# Run core tests
npm test

# Run all tests and get a summary report
npm run test:all

The test suite includes:

Unit and integration tests
Manual tool testing
Docker container tests
Smithery.ai integration tests

For detailed information about testing, see docs/testing.md.

Empower your AI agents with the perfect images, every time.
Built with ❤️ for developers and AI enthusiasts.