Skip to main content
Glama

Unsplash API MCP Server

README.md6.85 kB
# Unsplash API - FastAPI + FastMCP <div align="center"> <img src="images/UNSPLASH-MCP.png" alt="Unsplash MCP"> </div> > Forked from [unsplash-api by @aliosmankaya](https://github.com/aliosmankaya/unsplash-api) ## Table of Contents - [Overview](#overview) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Running](#running) - [API Endpoints](#api-endpoints) - [Search](#search) - [Photos](#photos) - [Random](#random) - [MCP Integration](#mcp-integration) - [MCP Overview](#mcp-overview) - [MCP Endpoints](#mcp-endpoints) - [Using with AI Models](#using-with-ai-models) - [Example Client](#example-client) - [Development](#development) - [License](#license) ## 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](https://github.com/tadata-org/fastapi_mcp) [FastAPI](https://github.com/fastapi/fastapi) ## Prerequisites Before using the Unsplash API, you need to: 1. [Register as a developer on Unsplash](https://unsplash.com/developers) 2. Obtain your Access Key 3. Configure the key as `UNSPLASH_CLIENT_ID` in the `.env` file ## Installation ### Using pip ```bash # 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 ```bash # 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 ```bash python main.py ``` The API will be available at `http://localhost:8000`. ### With Docker ```bash 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 <img src="images/main-page.png" alt="API Swagger UI"> ### 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:** ``` GET /search?query=mountains&page=1&per_page=5&order_by=latest ``` **Response Example:** ```json [ { "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:** ```json [ { "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:** ```json [ { "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](https://unsplash.com/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](https://github.com/tadata-org/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: ```python 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](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.

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