unsplash-mcp-server

A production-ready Model Context Protocol (MCP) server for the Unsplash API. It gives AI assistants — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and any MCP client — tools to search and fetch Unsplash photos, collections, topics, users, and stats, with Unsplash-guideline compliance built in (ready-to-use attribution and download tracking). Sign in once via OAuth to also manage your own profile, collections, and photo metadata.

[!IMPORTANT] Unofficial project. This is not affiliated with, endorsed by, or sponsored by Unsplash. "Unsplash" is a trademark of its respective owner. You use it under your own Unsplash API account and are responsible for complying with the Unsplash API Terms & Guidelines.

Table of contents

• Features
• Quick start
• Example interaction
• Configuration
• OAuth sign-in (optional)
• Tools
  • Tool reference
  • Output shape
  • Resources & prompts
• Example prompts
• Attribution & compliance
• Rate limits
• Handling of Unsplash text
• Privacy & security
• Troubleshooting
• FAQ
• Requirements
• Compatibility
• Roadmap
• Contributing
• Contact & community
• License

Features

• 29 tools across photos, search, users, collections, topics, stats, and your own profile — 21 read-only out of the box, plus 8 write/me tools once you sign in.
• Compliance built in — every photo comes with ready-to-use attribution (plain text + UTM-tagged HTML), and a dedicated unsplash_track_download tool for the download-tracking guideline.
• Content safety — content_filter=high by default on search and random photos.
• Flexible image URLs — each photo returns raw/full/regular/small/thumb sizes, plus a raw imgix base for custom sizes (?w=&h=&q=&fm=&fit=).
• Token-efficient output — full Unsplash responses are trimmed to a compact shape (URLs + metadata as text, never base64 image blobs) to keep model context small.
• Robust — typed failures returned as MCP isError results the model can recover from, plus retries/backoff, timeouts, 403 hourly-limit handling, and rate-limit surfacing.
• Safe — access-key redaction in all error output, an SSRF guard on download URLs, and untrusted-text handling guidance for indirect prompt-injection defence.
• Lean & modern — ESM, Node 20+, zero-install via npx, no telemetry.

Quick start

1. Get an Unsplash access key

Register an application at unsplash.com/developers → New Application → accept the API terms → copy its Access Key (not the Secret Key). New apps start on the Demo tier (50 requests/hour); the Production tier (5,000/hour) requires Unsplash's review from your app dashboard. See Rate limits.

2. Add the server to your MCP client

Claude Desktop — edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

Restart the client. See Configuration for every supported variable.

<details> <summary><b>Other clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)</b></summary>

Claude Code (CLI):

claude mcp add unsplash \
  --env UNSPLASH_ACCESS_KEY=your_access_key \
  --env UNSPLASH_APP_NAME=your_registered_app_name \
  -- npx -y @hanoak/unsplash-mcp-server

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project): use the exact same mcpServers block as Claude Desktop above.

Windsurf — ~/.codeium/windsurf/mcp_config.json: same mcpServers block as Claude Desktop above.

VS Code — .vscode/mcp.json (note the top-level key is servers, not mcpServers):

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

Any other MCP client — run the server over stdio with:

UNSPLASH_ACCESS_KEY=your_access_key npx -y @hanoak/unsplash-mcp-server

Point your client's stdio transport at command: npx, args: ["-y", "@hanoak/unsplash-mcp-server"], and pass the key via env.

</details>

3. Try it

Restart your client and ask:

"Find me a photo of mountains on Unsplash and show the attribution."

Example interaction

A typical flow: the model calls unsplash_search_photos, picks a result, presents the image with its attribution, and calls unsplash_track_download when it actually uses the photo.

You: Find a landscape photo of a foggy pine forest and credit the photographer.

Assistant: (calls unsplash_search_photos with query: "foggy pine forest", orientation: "landscape", picks the best result, then calls unsplash_track_download with its download_location) Here's a great match — Photo by Jane Doe on Unsplash — along with a ready-to-embed credit line and the image URL.

Each tool returns a compact JSON payload. Here's the shape of a single photo result (illustrative values):

<details> <summary><b>Example tool output</b></summary>

{
  "photo": {
    "id": "Dwu85P9SOIk",
    "description": "brown rocky mountain under blue sky during daytime",
    "width": 6000,
    "height": 4000,
    "color": "#734940",
    "blur_hash": "L6Pj0^i_.AyE_3t7t7R**0o#DgR4",
    "urls": {
      "raw": "https://images.unsplash.com/photo-1465…?ixid=…",
      "full": "https://images.unsplash.com/photo-1465…?ixid=…&q=85",
      "regular": "https://images.unsplash.com/photo-1465…?ixid=…&w=1080",
      "small": "https://images.unsplash.com/photo-1465…?ixid=…&w=400",
      "thumb": "https://images.unsplash.com/photo-1465…?ixid=…&w=200"
    },
    "photo_page": "https://unsplash.com/photos/Dwu85P9SOIk",
    "download_location": "https://api.unsplash.com/photos/Dwu85P9SOIk/download?ixid=…",
    "photographer": {
      "name": "Jane Doe",
      "username": "janedoe",
      "profile": "https://unsplash.com/@janedoe"
    },
    "attribution": {
      "text": "Photo by Jane Doe on Unsplash",
      "html": "Photo by <a href=\"https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral\">Jane Doe</a> on <a href=\"https://unsplash.com/?utm_source=your_app&utm_medium=referral\">Unsplash</a>",
      "photographerName": "Jane Doe",
      "photographerUrl": "https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral",
      "unsplashUrl": "https://unsplash.com/?utm_source=your_app&utm_medium=referral"
    }
  },
  "rate_limit": { "limit": 50, "remaining": 49 }
}

Every tool result includes a rate_limit object (limit, remaining) read from the Unsplash response headers. List/search tools wrap results in photos/collections/users/topics arrays with pagination fields (total, total_pages, count, page, per_page).

</details>

Configuration

Configuration is entirely via environment variables — no config files, no flags for secrets.

| Environment variable | Required | Description | | ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | UNSPLASH_ACCESS_KEY | yes | Your Unsplash API access key. The server exits at startup with a clear message if it is missing or blank. | | UNSPLASH_APP_NAME | recommended | Your registered Unsplash app name, used as the attribution utm_source. Defaults to a generic value (with a startup warning) if unset. | | UNSPLASH_SECRET_KEY | only for login | Your Unsplash app's secret key. Only needed to run login — see OAuth sign-in. | | UNSPLASH_OAUTH_REDIRECT_URI | only for login | Override the default http://localhost:8734/callback used by login. Must match the redirect URI registered on your Unsplash app. | | LOG_LEVEL | no | debug | info | warn | error (default info). All logs go to stderr; stdout carries only the MCP protocol. |

CLI flags: --version and --help are supported (e.g. npx @hanoak/unsplash-mcp-server --version). login/logout are subcommands, not flags — see below.

OAuth sign-in (optional)

The 21 core tools work out of the box with just UNSPLASH_ACCESS_KEY. To also use the 8 write/me tools (update your profile, manage collections, edit photo metadata), sign in once via OAuth:

1. On your app's page at unsplash.com/oauth/applications, add http://localhost:8734/callback as a redirect URI, and copy the Secret key.

2. Set both UNSPLASH_ACCESS_KEY and UNSPLASH_SECRET_KEY in your shell (not just the MCP client config — login runs from your terminal).

3. Run:

   npx @hanoak/unsplash-mcp-server login
   

   This opens your browser to Unsplash's consent screen, captures the redirect on a short-lived local server, exchanges the code for a user access token, and saves it to ~/.config/unsplash-mcp-server/credentials.json (owner-only file permissions). Unsplash user access tokens don't expire, so this is a one-time step — no periodic re-auth.

4. Restart your MCP client. The 8 write/me tools are now available; the 21 read-only tools are unaffected either way.

Run npx @hanoak/unsplash-mcp-server logout at any time to remove the stored token. To revoke it server-side, regenerate your app's secret key from the Unsplash dashboard.

Tools

All tools are namespaced unsplash_*. Most are read-only (annotated readOnlyHint: true); the exceptions are unsplash_track_download (registers a download event) and the 8 write/me tools below, all marked non-read-only and gated behind OAuth sign-in. Parameters map to the Unsplash API; per_page and stats quantity are clamped to a max of 30, and page is 1-based.

| Domain | Tools