<p align="center"><em>Proudly Made in Nebraska. Go Big Red! 🌽 <a href="https://xkcd.com/2347/">https://xkcd.com/2347/</a></em></p>

# Unsplash+ MCP

A private, local MCP server that drives a dedicated Chrome profile to sign in to an Unsplash+ account, search Plus-only results, and download licensed images.

This project automates the Unsplash website rather than using its API. Website automation is fragile and may conflict with Unsplash's terms. It deliberately does not bypass CAPTCHA, MFA, bot detection, or other access controls.

## Requirements

- Node.js 22 or newer
- Google Chrome installed
- [`pass`](https://www.passwordstore.org/) entries:
  - `unsplash/login`
  - `unsplash/password`
- An active single-user Unsplash+ subscription

Only the first line of each `pass` entry is read. Credentials are entered directly into the visible Chrome login form and are never returned over MCP.

## Install and build

```sh
npm install
npm run build
```

Add the server to an MCP client using:

```json
{
  "mcpServers": {
    "unsplash-plus": {
      "command": "node",
      "args": ["/absolute/path/to/UnSplashPlusMCP/dist/src/index.js"]
    }
  }
}
```

Chrome is visible by default. If Unsplash presents CAPTCHA, MFA, or another verification step, complete it in Chrome and then call `unsplash_plus_continue_login`.

## Tools

- `unsplash_plus_login`
- `unsplash_plus_continue_login`
- `unsplash_plus_status`
- `unsplash_plus_search`
- `unsplash_plus_get`
- `unsplash_plus_download`
- `unsplash_plus_logout`

Downloads default to `~/Downloads/unsplash-plus-mcp`. Each image receives a JSON receipt with source metadata and a SHA-256 checksum.

## Configuration

| Variable | Default |
| --- | --- |
| `UNSPLASH_PLUS_OUTPUT_DIR` | `~/Downloads/unsplash-plus-mcp` |
| `UNSPLASH_PLUS_PROFILE_DIR` | `~/Library/Application Support/unsplash-plus-mcp` |
| `UNSPLASH_PLUS_DIAGNOSTICS_DIR` | `<profile>/diagnostics` |
| `UNSPLASH_PLUS_LOGIN_ENTRY` | `unsplash/login` |
| `UNSPLASH_PLUS_PASSWORD_ENTRY` | `unsplash/password` |
| `UNSPLASH_PLUS_TIMEOUT_MS` | `30000` |
| `UNSPLASH_PLUS_HEADLESS` | unset; use `1` only after interactive login is complete |

Run `npm test` for unit tests and `npm run check` for strict type checking.