visual-hunt-mcp

visual-hunt-mcp is a local TypeScript MCP server for macOS that connects to your existing Chrome session over CDP and helps Codex / Claude find visually strong image candidates for posters, wallpapers, and inspiration boards.

v0.4.0 · 11 tools · audited end-to-end · 15/15 behavioural tests pass · 108 images downloaded in a real-world 10-topic stress test · ships with eval suite and full-test harness.

It is designed to:

• use the official @modelcontextprotocol/sdk with McpServer and registerTool
• connect to a local Chrome instance via chromium.connectOverCDP(...)
• reuse your local logged-in browser profile when you choose to do manual-assisted review
• avoid bypassing paywalls, login walls, CAPTCHA, or platform controls
• return candidate metadata and optionally download image files into a project folder created under the MCP server's current working directory

Why CDP

This project uses Chrome DevTools Protocol instead of launching a fresh automation browser so the MCP server can reuse a local Chrome profile you control. That makes Instagram and Xiaohongshu workflows more practical because the browser session can already be logged in, while the MCP server still stays local on your Mac.

Why Instagram / Xiaohongshu Are Manual-Assisted

Instagram and Xiaohongshu often require login, can change layout frequently, and may gate content behind platform controls. This MCP deliberately opens those pages in your connected local Chrome and only extracts visible public image candidates when available. It does not try to bypass login, rate limits, or access restrictions.

Download Scope

This project can now download image files for sources such as Unsplash, Pexels, Pixabay, wallpaper sites, and visible image URLs surfaced from manual-assisted social browsing when your connected Chrome session has access. A few guardrails still apply:

• Google-hosted previews and Google Maps imagery stay blocked
• Instagram and Xiaohongshu still depend on your connected Chrome login state and whatever visible image URLs the page actually exposes
• you are still responsible for checking licensing before reuse
• save_candidates_json remains metadata-only, while download_candidate_images writes image files plus a download manifest

Features

MCP tools (11)

Tool	Reliability	Notes
search_wallpaper_sites	★★★★★	Flagship. Curated 6-source set (Unsplash, Pexels, Pixabay, Wikimedia, Wallhaven, Alpha Coders). 100% topic coverage in stress tests.
open_xiaohongshu_visual_search	★★★★★	Flagship for travel/design topics. 100% topic coverage.
open_google_maps_visual_search	★★★	Manual-assisted. Most images correctly blocked from download by design — use for visual inspiration.
open_pinterest_visual_search	★★	Manual-assisted. Pinterest serves a login modal on most searches; log in via Chrome, then call extract_manual_page_candidates.
open_instagram_visual_search	★★	Manual-assisted. Same login-wall pattern as Pinterest.
search_google_images	★★	Inconsistent due to Google's lazy-loaded udm=2 layout. Prefer search_wallpaper_sites for primary search.
open_url_and_extract_images	★★★★	Generic extractor. Works on Wikipedia, blogs, brand pages.
extract_manual_page_candidates	★★★★★	Re-extract after manual scroll/login on a held page.
close_manual_page	★★★★★	Cleanup. Idempotent.
save_candidates_json	★★★★★	Metadata-only persistence.
download_candidate_images	★★★★★	Download with referer + user-agent from connected Chrome. Google-hosted previews are blocked by design.

Default source set (v0.4.0 curated)

The default search_wallpaper_sites source list was trimmed in v0.4.0 from 13 sources to the 6 that returned downloadable candidates on >80% of topics in real-world stress testing:

1. Unsplash — modern editorial photography
2. Pexels — modern editorial photography
3. Pixabay — modern editorial photography
4. Wikimedia Commons — landmarks, architecture, public-domain
5. Wallhaven — top free 4K/8K wallpapers
6. Alpha Coders / Wallpaper Abyss — top free 4K/8K wallpapers

Adapters for the dropped sources still ship — pass them explicitly when you need them: sites: ["openverse.org", "loc.gov", "images.nasa.gov", "rawpixel.com", "publicdomainpictures.net", "wallpaperscraft.com", "hdqwalls.com"].

Candidate scoring

Each candidate gets a lightweight scoreHint based on:

• image size
• aspect ratio closeness to common poster / wallpaper ratios
• title or alt text keywords such as poster, cinematic, wallpaper, 4k, 8k, travel, film, and landscape

Install

cd /Users/lanston/Desktop/Codex/visual-hunt-mcp
npm install

Start Chrome For MCP

npm run chrome:debug

This helper binds Chrome remote debugging to 127.0.0.1 only. It does not expose the CDP port publicly.

If you prefer the raw script:

chmod +x scripts/start-chrome-mcp.sh
./scripts/start-chrome-mcp.sh

Validation Workflow

Run the deterministic MCP smoke test after Chrome is up:

npm run smoke

For a comprehensive behavioural sweep covering all 11 tools (schema coercion, query optimization, manual-page lifecycle, login-wall suppression, false-positive filters, security guards):

node scripts/full-test.mjs              # 15 cases including live Chrome paths
node scripts/full-test.mjs --skip-live  # 10 cases, fast, no browser deps

What npm run smoke validates:

• the local MCP server starts over stdio from the current dist/ output
• tools/list exposes the expected tool set
• open_url_and_extract_images can extract visible candidates from a local fixture page
• extract_manual_page_candidates and close_manual_page are exposed for manual-assisted follow-up flows
• save_candidates_json writes candidate metadata to a temporary output root
• download_candidate_images downloads an allowed local image and skips a blocked Google-hosted candidate with a clear reason

The smoke test uses a temporary VISUAL_HUNT_OUTPUT_ROOT and cleans it up on success. To keep the artifacts for inspection:

npm run smoke -- --keep-output

For a higher-confidence pass that also hits live Google Images and wallpaper search flows through your connected Chrome session:

npm run smoke:live

Use npm run validate as the stable default validation command. It now runs npm run build first and then the deterministic smoke test.

Run MCP Locally

npm run dev

For production-style use:

npm run build
node dist/index.js

Claude Desktop Config

{
  "mcpServers": {
    "visual-hunt": {
      "command": "node",
      "args": [
        "/Users/lanston/Desktop/Codex/visual-hunt-mcp/dist/index.js"
      ],
      "env": {
        "CHROME_CDP_ENDPOINT": "http://127.0.0.1:9222"
      }
    }
  }
}

Example Prompts

Use visual-hunt to search_google_images for "cinematic Oahu Hawaii sunset travel poster 8k", limit 10.

Use visual-hunt to search_wallpaper_sites for "dark luxury black gold abstract 8k wallpaper", limit 15.

Use visual-hunt to open_xiaohongshu_visual_search for "夏威夷 绝美 海报 壁纸 旅行 摄影", limit 10.

Use visual-hunt to download_candidate_images for project "oahu-poster-board" using the candidates from the last search, limit 5.

Use visual-hunt to extract_manual_page_candidates for the manualPageId from the Xiaohongshu search after I log in or scroll more.

Notes

• Logs are written to stderr only so MCP JSON-RPC on stdout stays clean.
• Chrome must already be running with remote debugging enabled.
• Output folders are created under the MCP server's current working directory by default. Example: /path/to/visual-hunt-mcp/<project>/images.
• Override the output root with VISUAL_HUNT_OUTPUT_ROOT if you want downloads somewhere else.
• save_candidates_json writes metadata to <output-root>/<project>/candidates.json.
• download_candidate_images writes image files to <output-root>/<project>/images and a manifest to <output-root>/<project>/downloads.json.
• scripts/smoke-test.mjs is the quickest way to validate the MCP contract end-to-end against a local server process.
• scripts/smoke-test.mjs validates the local server through the current dist/ output and uses a temporary output root for artifacts.
• The server does not store credentials.
• The server does not execute arbitrary shell commands.

Environment variables

Var	Default	Effect
CHROME_CDP_ENDPOINT	http://127.0.0.1:9222	Chrome remote-debugging endpoint
VISUAL_HUNT_OUTPUT_ROOT	process.cwd()	Root directory for downloaded images and manifests
VISUAL_HUNT_TIMEOUT_MS	20000	Per-page navigation/extraction timeout
VISUAL_HUNT_MANUAL_PAGE_TTL_MS	1800000 (30 min)	TTL for entries in the manual-page registry; getManualPage refreshes
VISUAL_HUNT_MANUAL_PAGE_MAX	50	Hard cap on manual-page registry size; oldest evicted first
VISUAL_HUNT_AUTO_REGISTER	unset	Set to 1 to rewrite ~/.claude.json with this server entry on every startup. Off by default since v0.3.0.

Manual Checks Beyond Smoke

When you want to sanity-check the live/manual-assisted parts of the product, these are the highest-value follow-ups after npm run smoke:

• npm run smoke:live
• open_instagram_visual_search with the same Chrome profile you plan to use day-to-day
• open_xiaohongshu_visual_search with that same profile if login is required
• open_google_maps_visual_search to confirm the manual-review note and non-bypass behavior still look right

Exact Mac Commands

cd /Users/lanston/Desktop/Codex/visual-hunt-mcp
npm install
npm run chrome:debug
npm run smoke
npm run smoke:live