unsplash-smart

This Unsplash Smart MCP Server exposes a specialized stock photo toolset that AI agents can call via the stock_photo tool. It interprets natural language prompts to search, select, and prepare Unsplash images with automatic attribution handling. The system is designed for contextual, project-aware image retrieval, returning URLs and necessary metadata so agents can download and embed images with correct attribution. To use it, configure Cursor (or your MCP client) to point to the server configuration and supply your Unsplash API key. When an agent asks for an image, the server analyzes the request, selects relevant subjects, and returns optimized image results tailored to the project type and intent, minimizing tool spamming and optimizing bandwidth through URL-first delivery. The integration includes automatic attribution management and subject extraction to fit into your project structure (Next.js, React, Vue, etc.).

Prerequisites:

• Node.js 18.x or higher
• npm (comes with Node.js)
• An Unsplash API access key

Local installation (recommended):

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Configure Cursor MCP settings:

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

4. Add this MCP server configuration (example):

{
  "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"
      }
    }
  }
}

5. Replace the path and API key with your actual values, save, and restart Cursor.

Via Docker (alternative and reliable):

1. Clone the repo and navigate into it:

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

2. Create a docker-compose.yml (example in the README):

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

3. Build and start the container:

docker-compose up -d

4. Configure Cursor MCP settings with the docker-based command:

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

5. Save and restart Cursor.

Prerequisites and notes:

• Ensure your environment variables (e.g., UNSPLASH_ACCESS_KEY) are provided where required.
• For Windows users, ensure proper path handling in the mcp.json config.

Tips and common issues:

• Ensure your Unsplash API key has the necessary permissions and quotas for image searches and retrieval.
• The server is designed to work with Cursor and other MCP-compatible agents; if you encounter connectivity issues, verify the cwd/path and that the environment variable is accessible to the running process.
• When using Docker, the container should be kept running; the setup supports automatic restarts on crashes and keeps a steady connection to Cursor.
• If you modify project structure or framework conventions, verify that the integration aligns with your project’s folder layout to enable automatic directory creation and organization.
• The API includes automatic attribution handling; ensure your usage complies with Unsplash terms and that attribution data is retrievable via the provided API endpoints.