hob_hunt_mcp

A unified MCP server for web search and page fetching, built on Playwright.

Two tools. One browser process. No redundancy.

---

Tools

hunt_site

Fetch one or more web pages using a stealth Playwright browser. Handles JavaScript-rendered content, redirects, anti-bot detection, and lazy-loaded content. Single URL or many — always pass an array.

Two modes:

• fetch (default) — Return page content as clean Markdown (or raw HTML).
• map — Return a JSON list of all URLs discovered on the page. Useful for site exploration before you decide what to fetch.

Set pages greater than 1 to follow same-domain links breadth-first, up to that many total pages — a lightweight site crawl without any extra dependencies.

Results for the same URL and options are cached in memory for the session (5-minute TTL), so repeated fetches inside a single agent run are instant.

hunt_search

Perform one or more Google searches in parallel using a stealth browser with human-like navigation and persistent session state. Pass multiple queries at once and get all results back in a single structured JSON response.

Set fetchTopN to automatically fetch the content of the top N result pages per query and append it to the response — search and read in one shot. Fetched pages are always sandboxed in EXTERNAL CONTENT delimiters.

On first run against a fresh IP, Google may show a CAPTCHA. Run the warmup script once (see below) to seed a valid session file — all future headless searches use it automatically.

---

Quick Start

1. Install dependencies

npm install

2. Install the Playwright browser

npm run install-browser

3. Build

npm run build

4. Warm up the search session (first time only)

This opens a visible browser window and runs a real Google search to seed the persistent session file. Do it once — all headless searches after this use the saved session.

node test/warmup_search.mjs

If Google shows a CAPTCHA in the browser window, solve it manually. The script waits up to two minutes, then saves the session and closes.

5. Configure in your MCP client

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hob_hunt": {
      "command": "node",
      "args": ["C:/c/apps/servers/hob_hunt_mcp/build/index.js"]
    }
  }
}

Debug mode (opens visible browser — useful for diagnosing CAPTCHA or inspecting pages):

{
  "mcpServers": {
    "hob_hunt": {
      "command": "node",
      "args": ["C:/c/apps/servers/hob_hunt_mcp/build/index.js", "--debug"]
    }
  }
}

---

Tool Reference

hunt_site

Parameter	Type	Default	Description
urls	string[]	(required)	URLs to fetch. Multiple URLs are fetched in parallel.
mode	string	"fetch"	fetch = return content; map = return discovered URLs
pages	number	1	Max pages to crawl per starting URL following same-domain links (1–20)
timeout	number	30000	Page-load timeout in ms
waitUntil	string	"load"	Navigation signal: load, domcontentloaded, networkidle, commit
extractContent	boolean	true	Strip navigation/ads via Readability; return only main content
maxLength	number	0	Truncate output to this many characters (0 = no limit)
returnHtml	boolean	false	Return raw HTML instead of Markdown
selector	string	""	CSS selector — extract only matching elements (empty = full page)
waitForSelector	string	""	Wait for this CSS selector to appear before extracting
scrollToBottom	boolean	false	Auto-scroll to trigger lazy-loaded content
extractLinks	boolean	false	Append a list of all outbound links found on the page
sandbox	boolean	false	Wrap output in EXTERNAL CONTENT security delimiters
waitForNavigation	boolean	false	Wait for a second navigation after initial load
navigationTimeout	number	10000	Timeout for the extra navigation wait in ms
disableMedia	boolean	true	Block images, stylesheets, fonts, and media
debug	boolean	false	Show the browser window

Returns (fetch mode): Page content as Markdown (or HTML), prefixed with title and URL. Multiple pages separated by horizontal rules.

Returns (map mode): JSON — { source, links: string[] }

---

hunt_search

Parameter	Type	Default	Description
queries	string[]	(required)	Search queries to run in parallel
limit	number	10	Max results per query (up to 100)
timeout	number	60000	Page-load timeout in ms
fetchTopN	number	0	Auto-fetch the top N result pages per query and append content (0–5)
noSaveState	boolean	false	Skip saving/loading persistent browser session
locale	string	"en-US"	BCP-47 locale for results
debug	boolean	false	Show the browser window (use to solve CAPTCHA manually)
stateDir	string	(see below)	Directory for persistent browser session files

Returns: JSON — { searches: [{ query, results: [{ title, link, snippet }] }] }

With fetchTopN > 0, also returns fetched page content sections appended below the JSON, each wrapped in EXTERNAL CONTENT security delimiters.

Default stateDir: C:/c/apps/servers/hob_hunt_mcp/browser-state

---

Why a Unified Server?

hunt_search and hunt_site share the same Playwright Chromium dependency and the same stealth browser singleton. Running them as separate servers means two browser processes and two MCP config entries. Running them together means one of each — leaner, faster, and tidier.

---

Requirements

• Node.js 18 or higher
• npm

---

Development

# Watch mode (auto-rebuild on save)
npm run dev

# Build
npm run build

# Run integration tests
node test/run_tests.mjs

# Warm up search session (first time)
node test/warmup_search.mjs

# Diagnose Google DOM structure (if search returns 0 results)
node test/diagnose_google.mjs

---

License

MIT

---

With Many Thanks

This project is built directly on the shoulders of two excellent open-source MCP servers by jae-jae:

• g-search-mcp — the Google search tool that hunt_search is derived from
• fetcher-mcp — the Playwright fetch server that hunt_site is derived from

Both are thoughtfully designed, well-documented, and actively maintained. The fingerprinting, stealth browser management, session persistence, and multi-selector extraction strategy that make this server actually work in the real world all trace back to jae-jae's original implementation. If you find value here, please consider starring those repositories. None of this would exist without them — and I say that as someone who did not fully understand what I was doing when I started.