# Photo MCP

Photo discovery for **Pinterest** and **Unsplash**, built with Bun. Uses website endpoints—not official developer APIs.

## Install

Requires [Bun](https://bun.sh/) 1.4+.

```sh
git clone https://github.com/amirrezasalimi/photo-mcp.git
cd photo-mcp
bun install
bunx playwright install chromium
```

## Connect your MCP client

Add this server to your client's MCP configuration. Replace `/absolute/path/photo-mcp` with your clone's path. If your client cannot find Bun, use the output of `which bun` as `command`.

```json
{
  "mcpServers": {
    "photos": {
      "command": "bun",
      "args": ["run", "/absolute/path/photo-mcp/src/index.ts"],
      "cwd": "/absolute/path/photo-mcp"
    }
  }
}
```

**OMP:** merge it into `~/.omp/agent/mcp.json`, then run `/mcp reload`.

## Use it

Ask your assistant:

- “Search Pinterest for minimalist interiors.”
- “Search Unsplash for mountain photography.”
- “Search Pinterest using this photo: https://example.com/photo.jpg.”
- “Find similar photos to this Pinterest Pin: https://www.pinterest.com/pin/123456789/.”

### Log in when needed

1. Ask “Log in to Pinterest” or “Log in to Unsplash.”
2. Log in yourself in the dedicated browser window. Leave it open.
3. Ask “Finish Pinterest login” or “Finish Unsplash login.”

Saved cookies are reused with plain fetch first. A headless browser is used only for authentication/challenge responses. No passwords go through chat. Ask for `session_status` to inspect local state, or `logout` to delete a site's saved profile.

## Tools

| Tool | Inputs |
|---|---|
| `search_pinterest` | `query`, optional `limit`, `cursor` |
| `search_unsplash` | `query`, optional `limit`, `cursor` |
| `search_pinterest_by_photo` | Public HTTPS `imageUrl`, optional `limit`, `cursor` |
| `similar_pinterest` | Numeric Pin ID or canonical Pin URL as `pin`, optional `limit`, `cursor` |
| `login_pinterest`, `login_unsplash` | None |
| `finish_login`, `session_status`, `logout` | `site`: `pinterest` or `unsplash` |

Searches return image links, available attribution, and `nextCursor`. For another page, pass it as `cursor` with the same tool, query/seed and limit. Limits: 1–25 per request, default 20; sites may return fewer. Similar results are recommendations, not guaranteed visual duplicates. Anonymous Pinterest `e1` IDs cannot seed `similar_pinterest`. Photo search accepts URLs, not local uploads.

## Optional SOCKS5

Add to the server configuration:

```json
"env": { "PHOTO_PROXY_URL": "socks5h://127.0.0.1:1080" }
```

`socks5h` uses proxy-side DNS. Direct HTTP also supports `socks5://user:password@host:1080`; browser login/fallback requires an unauthenticated SOCKS proxy. Failed proxy connections never silently fall back to a direct connection.

## Privacy and limitations

- Sessions stay in `~/.photo-discovery-mcp/sessions/`. Treat these files as account credentials; never commit or share them. Override with `PHOTO_SESSION_DIR` if needed. Only one MCP process can own a browser profile at a time.
- Logging out deletes the dedicated local profile, not remote sessions or manually configured cookies. Advanced direct HTTP setup can use `PINTEREST_COOKIE` / `UNSPLASH_COOKIE` environment variables.
- Login needs a visible browser and user interaction. Normal searches are fetch-first; fallback browsers close after 60 idle seconds. Login windows expire after 10 idle minutes.
- Private endpoints can change, rate-limit, or deny access. No CAPTCHA solving or access-control bypass. Respect site terms and image licenses; this project is not affiliated with either site.
- Verified: Pinterest search and pagination with saved cookies, browser session lifecycle, and MCP tool calls. Unsplash direct access and Pinterest photo/related searches encountered access restrictions; authenticated success for those paths is not yet verified. Type checking previously exhausted the compiler heap/timed out; runtime smoke checks passed.

## Development

```sh
bun start
bun run check
```

MIT licensed.