Unsplash MCP Server
About
# Unsplash MCP Server This project implements a Model Context Protocol (MCP) server that provides tools for interacting with the Unsplash API, allowing users to search for and download photos. [
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Unsplash MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Requires Node.js v18+, Bun, and an Unsplash Access Key. Set up by cloning the repo, installing dependencies with bun install, configuring .env with UNSPLASH_ACCESS_KEY, then building with bun run build. Run standalone with bun run build/index.js. For use with Cline, configure MCP settings with the command and environment variable.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"unsplash mcp server": {
"upsplash-mcp-server": {
"command": "bun",
"args": [
"run",
"build"
]
}
}
}
}McpServers
{
"upsplash-mcp-server": {
"command": "bun",
"args": [
"run",
"build"
]
}
}Unsplash MCP Server
This project implements a Model Context Protocol (MCP) server that provides tools for interacting with the Unsplash API, allowing users to search for and download photos.
(Note: Replace @shariqriazz with the correct username/namespace if needed)
Git Repository: https://github.com/shariqriazz/upsplash-mcp-server (Please update if this is not the correct URL)
Features
Provides MCP tools to interact with the Unsplash API.
Search for photos based on queries, pagination, and orientation.
Download photos at specified resolutions (raw, full, regular, small).
Requires an Unsplash Access Key configured via environment variables.
Downloads photos to a local unsplash/ directory within the workspace.
Tools Provided
search_photos: Searches for photos on Unsplash.
Input Schema:
{
"type": "object",
"properties": {
"query": { "type": "string", "description": "The search term(s)." },
"page": { "type": "number", "description": "Page number (default: 1).", "default": 1 },
"per_page": { "type": "number", "description": "Items per page (default: 10, max: 30).", "default": 10, "maximum": 30 },
"orientation": { "type": "string", "enum": ["landscape", "portrait", "squarish"], "description": "Filter by orientation." }
},
"required": ["query"]
}
Output: Returns JSON data containing search results and a formatted text summary with image links.
download_photo: Downloads an Unsplash photo to the workspace's unsplash/ folder after triggering the download tracking event.
Input Schema:
{
"type": "object",
"properties": {
"photo_id": { "type": "string", "description": "The ID of the photo to download." },
"resolution": { "type": "string", "enum": ["raw", "full", "regular", "small"], "description": "Desired resolution (default: raw).", "default": "raw" },
"filename": { "type": "string", "description": "Optional filename (e.g., my-image.jpg). Defaults to sanitized description or {photo_id}.jpg." }
},
"required": ["photo_id"]
}
Output: Returns a success message with the path to the downloaded file. (Note: Schemas are illustrative. The server exposes the exact schemas via MCP.)
Prerequisites
Node.js (v18+ recommended)Bun (
npm install -g bun)Unsplash Account and API Access Key (https://unsplash.com/developers)
Setup & Installation
1. Clone the Repository:
git clone https://github.com/shariqriazz/upsplash-mcp-server.git # Update URL if needed
cd upsplash-mcp-server
2. Install Dependencies:
bun install
3. Configure Environment:
Create a
.env file in the project root (or copy .env.example if provided).Add your Unsplash Access Key:
UNSPLASH_ACCESS_KEY="YOUR_UNSPLASH_ACCESS_KEY"
4. Build the Server:
bun run build
This compiles the TypeScript code to
build/index.js.
Usage (Standalone / NPX)
Standalone (Local Build):
You can run the compiled server directly using bun or node. Ensure the UNSPLASH_ACCESS_KEY environment variable is set in your shell or .env file.
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
