unsplash-mcp

A Model Context Protocol server that exposes the Unsplash API as tools usable by MCP-compatible clients (Claude Desktop, Windsurf, Cursor, etc.). Built with Bun + TypeScript.

Installation

npm install -g unsplash-mcp
# or
bun add -g unsplash-mcp

Features

Tools provided by the server:

• search_photos — search Unsplash photos by keyword with filters (color, orientation, content filter, etc.)
• search_collections — search collections by keyword
• search_users — search users by keyword
• get_random_photo — random photo(s) with optional filters (query/topics/collections/orientation/count)
• get_photo — fetch a single photo by id
• list_photos — editorial photo feed
• track_photo_download — hit the required download tracking endpoint
• get_user — public user profile
• list_user_photos — photos uploaded by a user
• list_topics — list topics
• get_topic — topic by id or slug

Prerequisites

• Bun >= 1.1 or Node.js >= 20
• An Unsplash developer account and Access Key — create an app at https://unsplash.com/oauth/applications

Usage

Set your Unsplash access key as an environment variable:

export UNSPLASH_ACCESS_KEY=your_access_key_here

Then run the server:

unsplash-mcp
# or
bun run /path/to/node_modules/.bin/unsplash-mcp

The server speaks MCP over stdio. Logs go to stderr; protocol messages go to stdout.

Configure with an MCP client

Example Claude Desktop / Windsurf config entry:

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Development

git clone https://github.com/yourusername/unsplash-mcp.git
cd unsplash-mcp
bun install
cp .env.example .env
# edit .env and set UNSPLASH_ACCESS_KEY
bun run dev

Authentication

This server uses Unsplash public authentication (Authorization: Client-ID <access key>). That is sufficient for all read-only endpoints exposed here. User-authenticated endpoints (liking photos, managing collections, etc.) are intentionally not included.

Project structure

src/
  index.ts      # MCP server entrypoint, tool definitions
  unsplash.ts   # Thin typed wrapper around the Unsplash REST API

License

MIT