Unsplash Java MCP Server

This is a Java-based Model Context Protocol (MCP) server that integrates with the Unsplash API to provide photo search and listing capabilities.

[!NOTE]

This project currently provides an initial implementation and does not yet cover the full feature set of the Unsplash API. Additional functionality will be added incrementally over time as new pull requests and feature requests are submitted.

Special thanks to Unsplash for providing the amazing high-quality photos and API used by this project.

Features

• searchPhotos: Search for photos on Unsplash by query.
• listPhotos: List photos on Unsplash.

For a more detailed overview of the system design and use cases, see the Architecture Documentation.

Getting Started

Follow these steps to quickly get the Unsplash Java MCP Server up and running.

1. Prerequisites

• Docker and Docker Compose
• An Unsplash Access Key. You can get one by creating an application on the Unsplash Developer Portal.

2. Clone and Setup

# Clone the project
git clone https://github.com/h2nguyen/Unsplash-Java-MCP-Server.git
cd Unsplash-Java-MCP-Server

# Create a .env file and add your Unsplash Access Key
echo "UNSPLASH_ACCESS_KEY=your_access_key_here" > .env

3. Run the Application

The recommended way to run the server for demonstration and testing is using Docker Compose. This starts both the MCP Server and the MCP Inspector.

[!NOTE]

The following commands work on Linux and macOS

# Build and run the application 
docker compose up -d --build

# Stop the application
docker compose down

4. Verify with MCP Inspector

1. Open the MCP Inspector UI at http://localhost:6274.
2. Select Transport Type: Choose SSE.
3. Enter Server URL: In the "URL" field, enter http://localhost:3001/sse.
4. Select Connection Type: Chose Direct.
5. Connect: Click the Connect button.
6. Explore: Use List Tools and Call Tool to test searchPhotos and listPhotos.

Troubleshooting Tips

• Connection: If running inside the Docker network from another container, use http://mcp-server:8080/sse. From your host machine, use http://localhost:3001/sse.
• Startup: It may take a few seconds for the Spring Boot application to be ready. Check logs with docker-compose logs -f.

Configuration for Clients (mcp.json)

To use this server with MCP-compatible clients like Claude Desktop, use the following configuration.

Connecting via SSE (Recommended)

Since this server is built using Spring Boot WebMVC, it uses the SSE (Server-Sent Events) transport. Ensure the server is running (e.g., via Docker Compose or ./gradlew bootRun) before connecting.

{
  "mcpServers": {
    "unsplash": {
      "type": "sse",
      "url": "http://localhost:3001/sse",
      "note": "This MCP server integrates with the Unsplash API. To use it with SSE transport, add this URL directly to the client configuration."
    }
  }
}

[!CAUTION] If you are running the server locally without Docker Compose, the default port is 8080, so the URL would be http://localhost:8080/sse.

Running via Docker

If you prefer to run the server as a standalone Docker container, you can still connect via SSE.

1. Build the image:

   docker build -t unsplash-java-mcp-server .
   

2. Run the container:

   docker run -d -p 8080:8080 -e UNSPLASH_ACCESS_KEY=your_access_key_here unsplash-java-mcp-server
   

3. Configure Client: Use the SSE URL http://localhost:8080/sse in your mcp.json.

Development

To run the server locally without Docker:

1. Ensure you have Java 21 installed.
2. Export your key: export UNSPLASH_ACCESS_KEY=your_access_key_here
3. Run: `.

... View full README on GitHub