Skip to main content
Glama
Sign In
enesjakozh

Unsplash API MCP Server

by gzpaitch
GitHub
Python
MIT License
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Unsplash API - FastAPI + FastMCP

Forked from unsplash-api by @aliosmankaya

Table of Contents

Overview

This project provides an API to access the Unsplash service, allowing you to search, list, and get random images. Additionally, it integrates the Model Context Protocol (MCP), enabling AI models like Claude to interact directly with the Unsplash API.

FastAPI-MCP FastAPI

Prerequisites

Before using the Unsplash API, you need to:

  1. Register as a developer on Unsplash
  2. Obtain your Access Key
  3. Configure the key as UNSPLASH_CLIENT_ID in the .env file

Installation

Using pip

# Clone the repository git clone https://github.com/your-username/unsplash-api-mcp.git cd unsplash-api-mcp # Install dependencies pip install -r requirements.txt # Configure environment variables cp .env.example .env # Edit the .env file and add your UNSPLASH_CLIENT_ID

Using Docker

# Clone the repository git clone https://github.com/your-username/unsplash-api-mcp.git cd unsplash-api-mcp # Configure environment variables cp .env.example .env # Edit the .env file and add your UNSPLASH_CLIENT_ID # Build and start the container docker compose up -d

Configuration

Create a .env file in the project root with the following content:

UNSPLASH_CLIENT_ID=your_access_key_here

Running

Locally

python main.py

The API will be available at http://localhost:8000.

With Docker

docker compose up -d

The API will be available at http://localhost:8000.

Access the interactive API documentation at http://localhost:8000/docs.

API Endpoints

Endpoint to search for images on Unsplash.

Endpoint: /search

Method: GET

Parameters:

  • query: Search term (Default: "nature")
  • page: Page number (Default: 1)
  • per_page: Number of photos per page (Default: 10)
  • order_by: Photo ordering (Default: "relevant", Options: "relevant", "latest")

Request Example:

GET /search?query=mountains&page=1&per_page=5&order_by=latest

Response Example:

[ { "alt_description": "mountain range under cloudy sky", "created_at": "2023-05-15T12:34:56Z", "username": "Photographer Name", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 123 }, ... ]

Photos

Endpoint to list photos from the Unsplash landing page.

Endpoint: /photos

Method: GET

Parameters:

  • page: Page number (Default: 1)
  • per_page: Number of photos per page (Default: 10)
  • order_by: Photo ordering (Default: "latest", Options: "latest", "oldest", "popular")

Request Example:

GET /photos?page=1&per_page=5&order_by=popular

Response Example:

[ { "alt_description": "scenic view of mountains during daytime", "created_at": "2023-06-20T10:15:30Z", "username": "Photographer Name", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 456 }, ... ]

Random

Endpoint to get random photos from Unsplash.

Endpoint: /random

Method: GET

Parameters:

  • query: Search term to filter random photos (Default: "nature")
  • count: Number of photos to return (Default: 1, Maximum: 30)

Request Example:

GET /random?query=ocean&count=3

Response Example:

[ { "alt_description": "blue ocean waves crashing on shore", "created_at": "2023-04-10T08:45:22Z", "username": "Photographer Name", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 789 }, ... ]

For more information about the Unsplash API, see the official documentation.

MCP Integration

MCP Overview

The Model Context Protocol (MCP) is a protocol that allows AI models to interact directly with APIs and services. This implementation uses FastAPI-MCP to expose the Unsplash API endpoints as MCP tools.

MCP Endpoints

The MCP server is available at /mcp and exposes all API endpoints as MCP tools:

  • search: Search for images on Unsplash
  • photos: List photos from the landing page
  • random: Get random photos

Using with AI Models

AI models that support MCP can connect to this API using:

http://your-server:8000/mcp

For Claude, you can configure the connection in the model settings or via API.

Example Client

You can test the MCP server with a simple Python client:

import requests def test_mcp_metadata(): """Test if the MCP server is working correctly.""" response = requests.get("http://localhost:8000/mcp/.well-known/mcp-metadata") if response.status_code == 200: print("MCP server working correctly!") print(f"Response: {response.json()}") else: print(f"Error: {response.text}") def list_mcp_tools(): """List the available tools in the MCP server.""" response = requests.post( "http://localhost:8000/mcp/jsonrpc", json={ "jsonrpc": "2.0", "id": 1, "method": "mcp/list_tools" } ) if response.status_code == 200: print("Available MCP tools:") for tool in response.json()["result"]["tools"]: print(f"- {tool['name']}: {tool['description']}") else: print(f"Error: {response.text}") if __name__ == "__main__": test_mcp_metadata() list_mcp_tools()

For more information about using MCP, see the MCP_USAGE.md file.

Development

To contribute to development:

  1. Clone the repository
  2. Install development dependencies: pip install -r requirements.txt
  3. Create a .env file with your Unsplash API key
  4. Run the server in development mode: python main.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

An API that exposes Unsplash image search, listing, and random photo capabilities as MCP tools, enabling AI models like Claude to directly interact with Unsplash's services.

  1. Table of Contents
    1. Overview
      1. Prerequisites
        1. Installation
          1. Using pip
          2. Using Docker
        2. Configuration
          1. Running
            1. Locally
            2. With Docker
          2. API Endpoints
            1. Search
            2. Photos
            3. Random
          3. MCP Integration
            1. MCP Overview
            2. MCP Endpoints
            3. Using with AI Models
            4. Example Client
          4. Development
            1. License

              Related MCP Servers

              • mcp-image-downloader

                qpd-v
                A
                security
                A
                license
                A
                quality
                Enables AI assistants to download images from URLs and perform basic image optimization tasks.
                Last updated -
                2
                4
                JavaScript
                Apache 2.0

              • Together AI Image MCP Server

                stefanskiasan
                A
                security
                A
                license
                A
                quality
                Enables the generation of images using Together AI's models through an MCP server, supporting customizable parameters such as model selection, image dimensions, and output directory.
                Last updated -
                1
                4
                JavaScript
                MIT License
                • Apple
                • Linux

              • MCP Server for Replicate

                tzafrir
                -
                security
                A
                license
                -
                quality
                A FastMCP server implementation that provides a standardized interface for accessing AI models hosted on Replicate's API, currently supporting image generation with customizable parameters.
                Last updated -
                2
                Python
                MIT License

              • Unsplash MCP Server

                hellokaton
                A
                security
                A
                license
                A
                quality
                A lightweight server that enables seamless integration with Unsplash's image library, allowing developers to search for high-quality photos with various filters directly from the Cursor editor.
                Last updated -
                1
                112
                Python
                MIT License

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/gzpaitch/Unsplash-MCP'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server