Photo MCP

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

Install

Requires Bun 1.4+.

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

Related MCP server: pinterest-mcp

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.

{
  "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

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:

"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

bun start
bun run check

MIT licensed.