ratduck-search-mcp

An MCP server that gives an agent the open web: it searches DuckDuckGo by scraping the no-JavaScript front end, scrapes any URL you point it at, and filters and re-ranks results so the agent gets the top handful instead of a wall of links.

No API keys. No headless browser. No search-provider bill. Not on the npm registry either — it installs straight from its GitHub Pages site.

Tools

Full parameter reference: docs/tools.md.

Related MCP server: LLM Researcher

Install

One-liner — checks your Node version, downloads the tarball, installs it globally, and prints the client config to paste:

curl -fsSL https://dixonsolutions.github.io/ratduck-search-mcp/install.sh | bash

Or do it by hand:

curl -fsSLO https://dixonsolutions.github.io/ratduck-search-mcp/ratduck-search-mcp-latest.tgz && npm install -g ./ratduck-search-mcp-latest.tgz

Download first, install second — npm 12 refuses to fetch tarball URLs unless you pass --allow-remote=all, and a local file works on every npm version. Every released version is at a stable URL; versions.json lists them.

Wire it into a client

Claude Code

claude mcp add ratduck -- ratduck-search-mcp

Claude Desktop / any client using mcpServers JSON

{
  "mcpServers": {
    "ratduck": {
      "command": "ratduck-search-mcp"
    }
  }
}

More clients and troubleshooting: docs/install.md.

Example

> ask the agent: "find the three best current pages on Rust async runtimes, and read the top one"

The agent calls ddg_top_results with count: 3, fetchContent: true, and gets back ranked results plus the page text — one round trip.

Programmatic use works too, since the package exports its internals (install the tarball as a project dependency the same way, npm install ./ratduck-search-mcp-latest.tgz):

import { search } from "ratduck-search-mcp/ddg";
import { topResults } from "ratduck-search-mcp/filter";
import { scrapeUrl } from "ratduck-search-mcp/scrape";

const response = await search({ query: "rust async runtime", maxResults: 25 });
const best = topResults(response.results, response.effectiveQuery, 3, { excludeHomepages: true });
const page = await scrapeUrl({ url: best[0].url, format: "markdown", maxChars: 4000 });

Configuration

All optional, all environment variables:

Safety notes

• Private-network guard. scrape_url resolves the target host and refuses loopback, RFC1918, link-local (including 169.254.169.254) and CGNAT addresses, so a URL that arrives from a web page cannot turn the server into an internal-network probe. Override with RATDUCK_ALLOW_PRIVATE=1 only when you mean it.

• Everything returned is untrusted. Search snippets and scraped pages are attacker-controllable text. The server declares this in its MCP instructions, but the client is what ultimately has to treat tool output as data rather than instructions.

• Rate limits. DuckDuckGo challenges bursty traffic. The server detects the challenge page, falls back from html.duckduckgo.com to lite.duckduckgo.com, spaces out paged requests, and reports what happened in the result's notices instead of failing silently.

• Be a good citizen. This scrapes a free service. Keep maxResults sane and don't hammer it.

Development

npm install
npm test          # unit tests, no network
npm run typecheck
npm run build
npm run test:live # hits DuckDuckGo for real

Architecture and contribution notes: docs/architecture.md, docs/contributing.md.

Releasing

Every push to main rebuilds the tarball and redeploys the Pages site, so the -latest.tgz URL always matches main. Bumping version in package.json additionally tags the commit and cuts a GitHub Release with the tarball attached — Releases are the permanent home of each version, Pages is the install surface in front of them. See docs/release.md.

License

MIT — see LICENSE.