Unsplash Smart Mcp Server

[](https://mseep.ai/app/drumnation-unsplash-smart-mcp-server)

🖼️ 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.

[](https://smithery.ai/server/@drumnation/unsplash-smart-mcp-server) [](https://www.npmjs.com/package/@drumnation/unsplash-smart-mcp-server)

🚀 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)

1. Clone the repository:

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

1. Install dependencies:

npm install

1. Configure your Cursor MCP settings:

• macOS: Edit ~/.cursor/mcp.json
• Windows: Edit %USERPROFILE%\.cursor\mcp.json
• Linux: Edit ~/.cursor/mcp.json

1. 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"
      }
    }
  }
}

1. 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

1. 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)

1. Clone the repository:

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

1. 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

1. Build and start the container:

docker-compose up -d

1. Configure your Cursor MCP settings:

• macOS: Edit ~/.cursor/mcp.json
• Windows: Edit %USERPROFILE%\.cursor\mcp.json
• Linux: Edit ~/.cursor/mcp.json

1. Add the following configuration:

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

1. 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:

1. Install the server in Cursor via Smithery:

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

1. 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](./docs/smithery-deployment.md).

🧩 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:

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

This process eliminates the traditional workflow of:

1. ~~Searching Unsplash manually~~
2. ~~Scrolling through hundreds of results~~
3. ~~Downloading images to random locations~~
4. ~~Moving files to the correct project folders~~
5. ~~Manually tracking attribution data~~
6. ~~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](./docs/windows-compatibility.md).

🛠️ API Reference

URL-First Approach: The Smart Choice

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

1. Storage Efficiency: Prevents AI agents from unnecessarily storing large binary data in their context
2. Bandwidth Conservation: Reduces data transfer between services, improving response times
3. Placement Flexibility: Allows developers to download images exactly where they're needed
4. Permission Management: Avoids filesystem permission issues in restricted environments
5. 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:

1. Attribution Data Capture: Every image download automatically stores photographer information
2. Metadata Embedding: Photographer details are embedded directly into image files
3. Attribution Database: A local database maintains a record of all image usage
4. Attribution Generators: Built-in tools create HTML and React attribution components
5. 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:

1. JSON: Structured data for custom implementations
2. HTML: Ready-to-use HTML page for website footer or credits section
3. 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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drumnation
• Source: drumnation/unsplash-smart-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.