Skip to main content
Glama
ericthered926

DuckDuckGo MCP Server

by ericthered926
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

DuckDuckGo MCP Server

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

npm version

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

Related MCP server: DuckDuckGo MCP Server

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.

Available Tools

2 tools

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.6.0
    • First observedduckduckgo_news_search
    • First observedduckduckgo_web_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation4/5

News and web searches are distinct, but the descriptions are nearly identical (both return 3 results with 150-char excerpts), which could cause an agent to confuse them when selecting a tool.

Naming Consistency5/5

Both tools follow a consistent duckduckgo_<type>_search pattern, making the naming predictable and clear.

Tool Count3/5

With only 2 tools, the server is minimal but still reasonably scoped for a search-only service. However, it feels thin compared to typical MCP servers.

Completeness3/5

Covers both web and news search, but lacks image, video, or other common search types, and provides no way to fetch full content from results, leaving some gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers