unsplashed-mcp

MCP server for the Unsplash photo API. 12 tools for searching photos, browsing collections, exploring topics, and discovering photographers.

Why?

• Other Unsplash MCP servers expose a single tool. This exposes 12 to handle common API calls, plus some extra goodies.
• Supports rate-limiting based on your limits
• Supports dual-transports
• Supports TLS via env vars

Usage

Designing and developing UIs. This is a great addition to your toolkit for injecting beautiful stock images. I plugged this into cursor while building a Shopify template for a store and it works great.

Requires Bun and an Unsplash access key.

Quick Start

No clone needed. Run directly with bunx:

UNSPLASH_ACCESS_KEY=your_key bunx unsplashed-mcp

Cursor / Claude Desktop

Add to your MCP settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):

{
  "mcpServers": {
    "unsplash": {
      "command": "bunx",
      "args": ["unsplash-mcp"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

HTTP (multi-tenant, stateless)

UNSPLASH_ACCESS_KEY=your_key TRANSPORT=http bunx unsplashed-mcp

Listens on http://localhost:3000/mcp. Clients pass their Unsplash key as a Bearer token:

Authorization: Bearer <unsplash_access_key>

HTTP Configuration

TLS

Credentials must not travel in cleartext. Two options:

Direct TLS:

TLS_CERT_FILE=/path/to/cert.pem TLS_KEY_FILE=/path/to/key.pem TRANSPORT=http bun src/index.ts

Reverse proxy (recommended):

nginx:

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /etc/ssl/certs/mcp.pem;
    ssl_certificate_key /etc/ssl/private/mcp.key;

    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy:

mcp.example.com {
    reverse_proxy /mcp localhost:3000
}

Ngrok:

ngrok http http://localhost:3000

Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:3000

Rate Limiting

Per-key rate limiting enforced in HTTP mode. Defaults to 50 req/hr (Unsplash demo tier). Set higher for production-approved apps (max 5000):

export RATE_LIMIT_PER_HOUR=1000
export TRANSPORT=http
bun src/index.ts

Environment Variables

| Variable | Default | Description | | --------------------- | ------- | --------------------------- | | UNSPLASH_ACCESS_KEY | — | Required for stdio mode | | TRANSPORT | stdio | stdio or http | | PORT | 3000 | HTTP listen port | | TLS_CERT_FILE | — | Path to TLS certificate | | TLS_KEY_FILE | — | Path to TLS private key | | RATE_LIMIT_PER_HOUR | 50 | Per-key rate limit (1–5000) |

Tools

| Tool | Description | | --------------------------------- | ------------------------------------------------------------------- | | unsplash_search_photos | Search photos by keyword with filters (color, orientation, order) | | unsplash_search_collections | Search photo collections by keyword | | unsplash_search_users | Search photographers by name or username | | unsplash_get_photo | Get full photo details (EXIF, location, tags, URLs) | | unsplash_random_photo | Get random photos with optional filters | | unsplash_list_photos | Browse the editorial photo feed | | unsplash_track_download | Track a photo download (required by Unsplash API guidelines) | | unsplash_get_user | Get a photographer's public profile | | unsplash_list_topics | Browse curated photo topics | | unsplash_get_topic_photos | Get photos for a specific topic | | unsplash_photographer_portfolio | 360 view: profile + photos + collections + stats (4 parallel calls) | | unsplash_collection_overview | Full collection: details + photos + related (3 parallel calls) |

Development

git clone https://github.com/your-org/unsplashed-mcp.git
cd unsplashed-mcp
bun install
cp .env.example .env   # add your UNSPLASH_ACCESS_KEY

bun start        # Run from source (stdio)
bun test         # Run tests
bun codegen      # Regenerate API client from OpenAPI spec
bun typecheck    # Type-check
bun lint         # Lint

MCP Inspector

bun mcp