Integrations
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.
Prerequisites
Before using the Unsplash API, you need to:
- Register as a developer on Unsplash
- Obtain your Access Key
- Configure the key as
UNSPLASH_CLIENT_ID
in the.env
file
Installation
Using pip
Using Docker
Configuration
Create a .env
file in the project root with the following content:
Running
Locally
The API will be available at http://localhost:8000
.
With Docker
The API will be available at http://localhost:8000
.
Access the interactive API documentation at http://localhost:8000/docs
.
API Endpoints
Search
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:
Response Example:
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:
Response Example:
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:
Response Example:
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:
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:
For more information about using MCP, see the MCP_USAGE.md file.
Development
To contribute to development:
- Clone the repository
- Install development dependencies:
pip install -r requirements.txt
- Create a
.env
file with your Unsplash API key - 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
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.
Related MCP Servers
- AsecurityAlicenseAqualityEnables AI assistants to download images from URLs and perform basic image optimization tasks.Last updated -24JavaScriptApache 2.0
- AsecurityAlicenseAqualityEnables 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 -14JavaScriptMIT License
- -securityAlicense-qualityA 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 -2PythonMIT License
- AsecurityAlicenseAqualityA 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 -1112PythonMIT License