DuckDuckGo MCP Server

A Model Context Protocol (MCP) server that provides DuckDuckGo search functionality for AI assistants.

Attribution: This project is a fork of zhsama/duckduckgo-mcp-server, originally created by zhsama. This fork adds English localization, news search, region support, time filtering, and modern tooling.

Features

• Web Search - Search the web with region-specific and time-filtered results
• News Search - Search recent news articles with source and date information
• Token Optimization - Configurable result limits, snippet truncation, and formatting for low-VRAM LLMs
• SafeSearch - Content filtering (strict, moderate, off)
• Region Support - Localized results for different countries
• Time Filtering - Filter results by day, week, month, year
• Rate Limiting - Configurable rate limits to prevent abuse
• Configurable Logging - Debug, info, warn, error, or none

Installation

Prerequisites

• Node.js >= 18.0.0 (tested with Node 24)
• npm

Install & Build

npm install
npm run build

Available Tools

duckduckgo_web_search

Performs a web search using DuckDuckGo.

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query (max 400 characters)
limit	number	No	DDG_MAX_RESULTS	Override default result limit (1-20)
count	number	No	DDG_MAX_RESULTS	[Deprecated: use limit] Number of results
safeSearch	string	No	"moderate"	Filter: "strict", "moderate", or "off"
region	string	No	"wt-wt"	Region code (e.g., "us-en", "uk-en", "de-de")
time	string	No	"all"	Time range: "day", "week", "month", "year", "all"

Example:

{
  "query": "TypeScript best practices",
  "count": 5,
  "region": "us-en",
  "time": "month"
}

duckduckgo_news_search

Search for recent news articles.

Parameter	Type	Required	Default	Description
query	string	Yes	-	News search query (max 400 characters)
limit	number	No	DDG_MAX_RESULTS	Override default result limit (1-20)
count	number	No	DDG_MAX_RESULTS	[Deprecated: use limit] Number of results
safeSearch	string	No	"moderate"	Filter: "strict", "moderate", or "off"
time	string	No	"all"	Time range: "day", "week", "month", "year", "all"

Example:

{
  "query": "artificial intelligence",
  "count": 10,
  "time": "week"
}

Supported Regions

Code	Region
wt-wt	Worldwide
us-en	United States
uk-en	United Kingdom
ca-en	Canada (English)
au-en	Australia
de-de	Germany
fr-fr	France
es-es	Spain
it-it	Italy
jp-jp	Japan
br-pt	Brazil
mx-es	Mexico
in-en	India

Other region codes following the xx-xx format may also work.

Configuration

Environment Variables

Token Optimization (for low-VRAM LLMs)

Variable	Default	Description
DDG_MAX_RESULTS	3	Default number of results returned
DDG_MAX_SNIPPET_LENGTH	150	Max characters per snippet (truncated with ...)
DDG_ENABLE_FULL_CONTENT	false	Set to "true" to disable truncation
DDG_STRIP_EMOJI	false	Set to "true" to remove emojis from titles/text
DDG_OUTPUT_FORMAT	"dense"	options: "dense", "json", "minimal"

Rate Limiting

Variable	Default	Description
RATE_LIMIT_PER_SECOND	1	Maximum requests per second
RATE_LIMIT_PER_MONTH	15000	Maximum requests per month

Logging

Variable	Default	Description
LOG_LEVEL	"info"	Logging level: debug, info, warn, error, none

Examples

# Token-optimized for low VRAM (12GB RTX 5070)
DDG_MAX_RESULTS=3 DDG_MAX_SNIPPET_LENGTH=150 npm run start

# Full content for high-VRAM systems
DDG_MAX_RESULTS=10 DDG_MAX_SNIPPET_LENGTH=500 DDG_ENABLE_FULL_CONTENT=true npm run start

# Debug logging
LOG_LEVEL=debug npm run start

Integration

Claude Desktop

Add to your Claude Desktop config:

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

{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@ericthered926/duckduckgo-mcp-server"]
    }
  }
}

MCPO (Open WebUI)

For MCPO integration:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@ericthered926/duckduckgo-mcp-server"],
      "env": {
        "DDG_MAX_RESULTS": "3",
        "DDG_MAX_SNIPPET_LENGTH": "150",
        "DDG_ENABLE_FULL_CONTENT": "false"
      }
    }
  }
}

Local Development

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

Development

Scripts

Command	Description
npm run build	Compile TypeScript
npm run start	Run the server
npm run dev	Watch mode for development
npm run lint	Run ESLint + Prettier check
npm run lint:fix	Auto-fix lint issues
npm run format	Format code with Prettier
npm run test	Run tests
npm run typecheck	TypeScript type checking only

Debugging

Use the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Project Structure

duckduckgo-mcp-server/
├── src/
│   └── index.ts          # Main server (web + news search)
├── test/
│   └── server.test.js    # Smoke tests
├── build/                 # Compiled output
├── .husky/               # Pre-commit hooks
├── eslint.config.js      # ESLint 9.x flat config
├── tsconfig.json         # Strict TypeScript config
├── .prettierrc           # Prettier formatting
├── .editorconfig         # Editor settings
└── .nvmrc                # Node version (24)

Rate Limits

Default rate limits are conservative to avoid being blocked by DuckDuckGo:

• 1 request per second - Prevents rate limiting
• 15,000 requests per month - Reasonable monthly cap

Adjust via environment variables if needed for your use case.

Troubleshooting

Server won't start

1. Check Node.js version: node --version (should be >= 18)
2. Rebuild: npm run build
3. Check for TypeScript errors in build output

Rate limit errors

• Wait for the limit window to reset (1 second for per-second, or adjust limits)
• Check if multiple instances are sharing the same counter

No results returned

• Try a different query or remove time filters
• Check if SafeSearch is blocking results
• DuckDuckGo may return no results for very specific queries

Debug logging

Enable debug logs to see detailed request information:

LOG_LEVEL=debug npm run start

Credits

This project is a fork of zhsama/duckduckgo-mcp-server, originally created by zhsama.

What's New in This Fork

• Token optimization - Configurable result limits & snippet truncation for low-VRAM LLMs
• Dense output format - Single-line results to minimize token usage
• URL cleaning - Strips tracking params (utm_*, fbclid, gclid, etc.)
• limit parameter - LLM can override defaults when more context needed
• English localization (all comments and output)
• News search tool (duckduckgo_news_search)
• Region/locale support for localized results
• Time range filtering
• Configurable logging via LOG_LEVEL
• Modern ESLint 9.x flat config
• Prettier formatting
• Husky pre-commit hooks
• Comprehensive test suite
• Strict TypeScript configuration

License

MIT - See LICENSE for details.