hanoak/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
Restart the client. See Configuration for every supported variable.
Other clients (Claude Code, Cursor, VS Code, Windsurf, generic stdio)
**Claude Code** (CLI):
**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):
**Any other MCP client** — run the server over **stdio** with:
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
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).