Unsplash
Model Context Protocol (MCP) server exposing the Unsplash API as tools.
Ask AI about Unsplash
Powered by Claude Β· Grounded in docs
I know everything about Unsplash. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 keywordsearch_usersβ search users by keywordget_random_photoβ random photo(s) with optional filters (query/topics/collections/orientation/count)get_photoβ fetch a single photo by idlist_photosβ editorial photo feedtrack_photo_downloadβ hit the required download tracking endpointget_userβ public user profilelist_user_photosβ photos uploaded by a userlist_topicsβ list topicsget_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/d0nj/unplash-mcp.git
cd unplash-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
