DuckDuckGo Search MCP Server

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