https://github.com/jeffkit/unsplash-mcp-server

MCP server for Unsplash photo search
https://github.com/jeffkit/unsplash-mcp-server

Last synced: 4 months ago
JSON representation

MCP server for Unsplash photo search

Host: GitHub
URL: https://github.com/jeffkit/unsplash-mcp-server
Owner: jeffkit
License: mit
Created: 2025-08-21T12:02:58.000Z (10 months ago)
Default Branch: main
Last Pushed: 2025-08-22T03:22:57.000Z (10 months ago)
Last Synced: 2025-10-28T17:49:28.335Z (8 months ago)
Language: JavaScript
Size: 31.3 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Unsplash MCP Server

[English](README.md) | [中文](README_CN.md)

A Model Context Protocol (MCP) server that provides photo search functionality using the Unsplash API with stdio transport.

## Features

- 🔍 Search photos on Unsplash with various filters
- 📄 Support for pagination, orientation filtering, and content filtering
- 📊 Returns formatted photo data including URLs, user info, and metadata
- 🖼️ Two response formats: base64-encoded images (default) or JSON with URLs
- 🔗 Uses stdio transport for seamless MCP integration
- ⚡ Command-line API key support for easy deployment
- 🚀 Concurrent image fetching for optimal performance

## Installation

### From npm (Recommended)

```bash
npm install -g @jeffkit/unsplash-mcp-server
```

### From source

```bash
git clone https://github.com/jeffkit/unsplash-mcp-server.git
cd unsplash-mcp-server
npm install
npm run build
```

## API Key Setup

Get your Unsplash API access key:
1. Visit https://unsplash.com/developers
2. Create a new application
3. Copy your Access Key

## Usage

### Command Line

```bash
# Using command line argument (default: image format)
npx -y @jeffkit/unsplash-mcp-server --access-key YOUR_API_KEY

# Using text format (returns JSON with URLs)
npx -y @jeffkit/unsplash-mcp-server --access-key YOUR_API_KEY --response-format text

# Using environment variable
UNSPLASH_ACCESS_KEY=YOUR_API_KEY @jeffkit/unsplash-mcp-server

# Show help
npx @jeffkit/unsplash-mcp-server --help
```

### MCP Client Integration

Add to your MCP client configuration:

```json
{
"mcpServers": {
"unsplash": {
"command": "npx",
"args": ["-y", "@jeffkit/unsplash-mcp-server", "--access-key", "YOUR_API_KEY"]
}
}
}
```

#### Claude Code
Especially for Claude Code, use the following command to add the MCP server to the MCP server list:

```bash
claude mcp add-json unsplash '{"command": "npx", "args": ["-y", "@jeffkit/unsplash-mcp-server", "--access-key", "YOUR_API_KEY"]}'
```

With text format (JSON URLs):

```json
{
"mcpServers": {
"unsplash": {
"command": "npx",
"args": ["-y", "@jeffkit/unsplash-mcp-server", "--access-key", "YOUR_API_KEY", "--response-format", "text"]
}
}
}
```

Or with environment variable:

```json
{
"mcpServers": {
"unsplash": {
"command": "npx",
"args": ["-y", "@jeffkit/unsplash-mcp-server"],
"env": {
"UNSPLASH_ACCESS_KEY": "YOUR_API_KEY"
}
}
}
}
```

### Development

```bash
npm run dev -- --access-key YOUR_API_KEY
npm run dev -- --access-key YOUR_API_KEY --response-format text
```

## Tools

### search_photos

Search for photos on Unsplash with configurable response format.

**Parameters:**
- `query` (required): Search term for photos
- `page` (optional): Page number (default: 1)
- `per_page` (optional): Number of photos per page (default: 10, max: 30)
- `orientation` (optional): Filter by orientation ("landscape", "portrait", "squarish")
- `content_filter` (optional): Content safety filter ("low", "high")

**Response Formats:**

#### Image Format (Default)
Returns base64-encoded images with metadata. Each image is returned as an MCP Image content type.

#### Text Format
Returns JSON with photo URLs and metadata:

```json
{
"total": 1000,
"total_pages": 100,
"current_page": 1,
"per_page": 10,
"results": [
{
"id": "photo_id",
"description": "Beautiful landscape",
"urls": {
"raw": "https://...",
"full": "https://...",
"regular": "https://...",
"small": "https://...",
"thumb": "https://..."
},
"user": {
"name": "Photographer Name",
"username": "username"
},
"dimensions": {
"width": 3000,
"height": 2000
},
"likes": 100,
"color": "#f0f0f0",
"created_at": "2023-01-01T00:00:00Z"
}
]
}
```

## Response Format Configuration

The server can be configured at startup to return either:

1. **Image format** (default): Base64-encoded images as MCP Image content with complete JSON metadata
2. **Text format**: JSON with photo URLs and metadata as MCP Text content

Choose the format based on your MCP client's capabilities and use case.

## Changelog

### v1.0.2
- ✨ Added complete image URLs in metadata for image mode
- 🔧 Use original Unsplash API response structure for data integrity
- 📚 Added Gemini CLI configuration examples
- 🌏 Added Chinese documentation

### v1.0.1
- 🐛 Various bug fixes and performance improvements

### v1.0.0
- 🎉 Initial release
- 🔍 Basic Unsplash photo search functionality
- 📊 Support for two response formats (image/text)
- ⚡ stdio transport support

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/jeffkit/unsplash-mcp-server

Awesome Lists containing this project

README