Unsplash

You can access Unsplash images programmatically through an MCP-enabled FastAPI server. This setup exposes the core Unsplash endpoints as MCP tools, allowing AI models and clients to search, list, or fetch random photos directly via MCP calls. Using MCP integration streamlines interactions with the image service from model-based workflows and automated pipelines.

How to use

You connect an MCP-enabled client to the server at your deployment URL followed by the MCP path. The MCP surface exposes three tools that correspond to the core Unsplash endpoints: search, photos, and random. Each tool lets you perform common image queries without manually handling web requests.

How to install

Prerequisites include Python and a working environment to run the API locally or in a container. You also need an Unsplash access key to retrieve images.

# Clone the project
git clone https://github.com/your-username/unsplash-api-mcp.git
cd unsplash-api-mcp

# Install dependencies
pip install -r requirements.txt

# Configure environment with your Unsplash key
cp .env.example .env
# Edit the .env file and add your UNSPLASH_CLIENT_ID

Configuration

Create a file named .env in the project root and set your Unsplash client ID as UNSPLASH_CLIENT_ID. This key authorizes requests to the Unsplash API.

UNSPLASH_CLIENT_ID=your_access_key_here

Running

Run the server locally to start serving API endpoints and MCP surface. The MCP surface is reachable at the standard server URL with the /mcp path.

python main.py

MCP integration details

The MCP surface exposes the Unsplash endpoints as tools under the MCP umbrella. The available tools are search, photos, and random. You can connect to the MCP surface using the standard MCP URL format.

Using MCP with AI models

Connect your MCP-enabled AI model to the server’s MCP endpoint to invoke the tools. The general MCP URL format is http://your-server:8000/mcp. You can then list tools, call the specific tools, and pass arguments as needed by your model’s MCP client.

Example client

A simple client can query the MCP surface to verify accessibility and enumerate available tools. The client can request the MCP metadata and list the tool names and descriptions to confirm the MCP surface is active.

Development

For development, install dependencies, configure the Unsplash key, and run the server in development mode. Make changes to the FastAPI app as needed and test the MCP surface locally.

License

This project is licensed under the MIT License. Review the license terms for usage, distribution, and contribution guidelines.

Available tools

search

Search for images on Unsplash with a query, page, per_page, and order_by parameters to retrieve matching results.

photos

List photos from the Unsplash landing page with page, per_page, and order_by options to paginate results.

random

Fetch one or more random photos filtered by a query with an optional count parameter.