Unsplash MCP Server

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](https://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.

Other clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)

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.

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

Example tool output

{

"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 Jane Doe on Unsplash ", "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).

Configuration

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

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.

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