Duckduckgo Websearch

A Model Context Protocol (MCP) server that provides web search and content fetching via DuckDuckGo. No API key required.

Features

• Web Search — Multi-page results (supports 10 ~ 100+ results via automatic pagination)
• Content Fetching — Fetch and parse any webpage to clean text
• Bot Detection & Retry — Automatically retries up to 3 times on DDG bot challenges
• Session Cookie Jar — Persists DDG session cookies in-memory across requests
• Advanced Query Syntax — Full support for DDG/Google-style operators (site:, OR, intitle:, etc.)
• Zero-Click Results — Instant answer cards (e.g. search ip, weather)
• Zero Dependencies at Runtime — Only cheerio + @modelcontextprotocol/sdk
• Node.js & Bun — Works with both runtimes (Node ≥ 18)

---

Installation

As MCP Server (global CLI)

npm install -g duckduckgo-websearch
# or
npx duckduckgo-websearch

As npm Library

npm install duckduckgo-websearch

---

MCP Server Usage

Claude Desktop

Edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ddg-search": {
      "command": "npx",
      "args": ["duckduckgo-websearch"]
    }
  }
}

Or with a local build:

{
  "mcpServers": {
    "ddg-search": {
      "command": "node",
      "args": ["/path/to/duckduckgo-mcp-server/build/index.js"]
    }
  }
}

Other MCP Clients

Any MCP-compatible client (Cursor, Cline, Continue, etc.) can connect via stdio transport using the same command above.

---

MCP Tools

search

Search DuckDuckGo and return paginated results.

Parameter	Type	Default	Description
query	string	required	Search query. Supports advanced syntax (see below)
max_results	integer	25	Number of results to return. Triggers automatic pagination when > 10

Advanced Query Syntax (DDG supports Google-style operators):

Syntax	Example	Effect
site:domain	site:github.com python	Restrict to a domain
site:a.com OR site:b.com	site:docs.python.org OR site:stackoverflow.com	Multiple domains
"exact phrase"	"model context protocol"	Exact match
-word	python -snake	Exclude keyword
intitle:word	intitle:tutorial python	Match in page title
filetype:ext	filetype:pdf machine learning	Filter by file type
OR / AND	python OR javascript async	Boolean operators

Response format:

Found 25 search results:

1. Page Title
   URL: https://example.com/page
   Summary: Brief description of the page content...

2. ...

---

fetch_content

Fetch and parse a webpage to clean, LLM-readable text.

Parameter	Type	Default	Description
url	string	required	Webpage URL to fetch
max_content_length	integer	8000	Maximum characters to return

---

Library Usage (Node.js / Bun)

import { WebSearch, WebFetcher } from 'duckduckgo-websearch';

// Search
const searcher = new WebSearch();

// Basic search — returns up to 10 results (1 page)
const results = await searcher.search('claude anthropic');

// Request more results — auto-paginates across multiple DDG pages
const results = await searcher.search('python tutorial', { maxResults: 50 });

// Advanced query syntax works natively in the query string
const results = await searcher.search('site:github.com mcp server typescript');
const results = await searcher.search('site:docs.python.org OR site:realpython.com async await');

// Format for LLM consumption
console.log(searcher.formatResultsForLLM(results));

// Fetch webpage content
const fetcher = new WebFetcher();
const content = await fetcher.fetchAndParse('https://example.com', 8000);

SearchResult type

interface SearchResult {
  title: string;
  link: string;
  snippet: string;
  position: number;
}

Error handling

import { WebSearch, SearchError } from 'duckduckgo-websearch';

try {
  const results = await searcher.search('query');
} catch (err) {
  if (err instanceof SearchError) {
    console.error(err.code); // 'BOT_DETECTED' | 'HTTP_ERROR' | 'TIMEOUT' | 'UNKNOWN'
    console.error(err.message);
  }
}

SearchError codes:

Code	Meaning
BOT_DETECTED	DDG bot challenge triggered after 3 retry attempts
HTTP_ERROR	Non-2xx HTTP response
TIMEOUT	Request timed out (30s limit)
UNKNOWN	Unexpected failure

---

Development

git clone https://github.com/HeiSir2014/duckduckgo-mcp-server
cd duckduckgo-mcp-server

npm install
npm run build          # compile TypeScript → build/

# Run example test (Bun)
bun example/test.ts

# Run with Node
node -e "require('./build/index.js')"

---

Architecture

src/
├── index.ts              # MCP server entry, tool definitions
├── duckduckgoSearcher.ts # Search logic: fetch, bot detection, retry, pagination
├── cookieJar.ts          # In-memory cookie jar for DDG session persistence
├── webContentFetcher.ts  # Webpage fetch + text extraction
├── rateLimiter.ts        # Token-bucket rate limiter
└── types.ts              # Shared types (SearchResult, SearchOptions, SearchError)

Pagination mechanism — DDG HTML endpoint returns 10 results per page with a vqd session token embedded in the "Next" form. When maxResults > 10, the searcher chains page requests using vqd and the form parameters (s, dc) extracted from each page's nav-link.

Bot detection — On each page fetch the searcher checks for missing result containers (.serp__results) and known challenge keywords. On detection it awaits the report ping (/t/sl_h) which warms the session, then retries. After 3 failures it throws SearchError('BOT_DETECTED').

---

Rate Limits

Operation	Limit
Search	30 requests / minute
Content Fetch	20 requests / minute

---

License

MIT