Searchfetch

SearchFetch

An MCP server that gives AI agents web search and page fetching through a stealth browser. Pages are rendered with JavaScript, stripped of noise, and returned as compact Markdown.

• Browser rendering: CloakBrowser runs Chromium with humanized input. Each fetch uses an isolated browser context. Sites may still demand logins or challenges.
• Fault tolerance: relaunches a disconnected browser and retries timeouts, network failures and HTTP 429 (honoring Retry-After, capped at 30 s) once. Built-in search engines fall back to DuckDuckGo HTML and then DuckDuckGo Lite.
• Token-efficient output: scripts, styles, SVGs, inline styles and embedded data: images are removed before conversion; images, media and fonts are blocked at the network layer.
• Template-driven extraction: JSON templates for GitHub, GitLab, npm, PyPI, crates.io, docs.rs, Docker Hub, Wikipedia, MDN, Reddit, YouTube, DEV, pkg.go.dev, Javadoc and generic documentation sites. Custom templates can be passed inline.
• Two runtimes: Python (uvx, Python 3.11.5+) or Node.js (npx, Node 24+), with the same tools, templates and output. The first run downloads the browser binary.

Setup

No manual install is needed. Point your MCP client at uvx or npx:

{
  "mcpServers": {
    "searchfetch": {
      "command": "uvx",
      "args": ["searchfetch"]
    }
  }
}

For Node.js, use "command": "npx", "args": ["-y", "searchfetch"]. In Cursor, add a command server with uvx searchfetch or npx -y searchfetch.

Tools

Both tools are read-only. Failures are returned as MCP tool errors.

websearch

Results are a numbered list of titles, URLs and snippets. When an engine fails or returns no results, the next template in its fallback chain is tried (google → duckduckgo-search → duckduckgo-lite-search), and a [websearch: …] note at the top of the output explains why.

webfetch

Output ends with a footer naming the template and the character window, plus the next start_index when more content remains. Pages that match no template are converted whole after removing navigation, headers, footers, sidebars, dialogs and media (template="auto (fallback)"). The raw template converts the full <body> with no removal.

Templates

Built-in templates live in templates/ and are shared by both runtimes. Page templates: github-repo, github-issue, npm-package, pypi-package, crates-package, docs-rs, javadoc, docs-page, docker-hub, wikipedia, gitlab, reddit, mdn-web-docs, devto, go-pkg, youtube, raw. Search templates: google-search, duckduckgo-search, duckduckgo-lite-search.

Templates are validated when they are loaded or passed inline:

Each section has a name, a selector (empty selects <body>), and optionally format (text, markdown, attribute with attribute, or html), transform (one or a list of strip, decode_google_url, decode_ddg_url, json_parse, resolve_href), required, multiple, max_items, and children (fields extracted from inside each matched element).

Selectors separated by top-level commas are ordered fallbacks: the first selector that matches wins, and an empty fallback selects the current element. Children search inside their parent element and its ancestors, never neighbouring results, so a missing field stays missing. Missing required sections or fields are reported as errors.

A records section whose first item has Author/User and Comment/Body fields is rendered as a comment thread; other records render as indented Key: value blocks.

Development

npm ci && uv sync --locked --extra dev
git config core.hooksPath .githooks   # optional: format, lint and unit tests before commits

npm test               # Node (node:test) and Python (pytest) unit tests
npm run lint           # ESLint and Ruff
npm run format         # Prettier and Ruff format (format:check to verify)
npm run e2e            # real browser against local fixtures, plus the packed npm and wheel builds
npm run check          # everything CI runs
npm run inspect:node   # MCP Inspector (inspect:py for Python)

Layout

The runtimes mirror each other module for module (templates, extract, markdown, compose, browser, server). Any change to one should be made to the other, with a shared fixture if the behavior is observable.

Releasing

Bump version in both package.json and pyproject.toml (then npm install and uv lock), commit, and push a matching tag:

git tag -a v4.0.1 -m "v4.0.1" && git push origin main v4.0.1

The Publish workflow checks that the tag matches both versions, runs lint and unit tests, publishes to npm and PyPI, and then creates the GitHub Release with generated notes. To retry a tag, run the workflow manually from the Actions tab with that tag.

Limits

• HTML-to-Markdown conversion uses turndown (Node) and markdownify (Python). They agree on common content, but edge cases such as tables differ.
• After the DOM is ready, each fetch waits up to five seconds for network activity to settle. Pages that keep rendering after that may return partial content.
• E2E tests use local fixtures. Live search-engine availability and third-party page layouts change over time and need separate live checks.