DuckDuckGo MCP / CLI

A Model Context Protocol (MCP) server and CLI that provide DuckDuckGo search functionality as MCP tools, resources, prompts, and a command-line interface.

Features

• Search Tool: Structured web, images, videos, and news search with parameters
• Prompts: Pre-built prompts for search analysis and research planning
• Resources: Discover supported DuckDuckGo region codes
• CLI: Run searches from your terminal with JSON output option

Use With MCP Clients

Configure via uvx (Claude Desktop)

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json under mcpServers:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/varlabz/duckduckgo-mcp",
        "duckduckgo-mcp"
      ]
    }
  }
}

Notes:

• Restart Claude Desktop after saving the config.

Configure via uvx (VS Code)

Add this to your workspace .vscode/mcp.json (or User settings JSON):

{
  "servers": {
    "duckduckgo": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/varlabz/duckduckgo-mcp",
        "duckduckgo-mcp"
      ]
    }
  }
}

Quick sanity check (optional)

Run the server ad-hoc via uvx to verify it starts:

uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-mcp

MCP Capabilities

• Tools: search — DuckDuckGo search across text (default), images, videos, or news.
  • Parameters:
    • query (string)
    • max_results (1–50, default 10)
    • categories (text|images|videos|news)
    • region (e.g., us-en; defaults to us-en when omitted)
    • safesearch (on|moderate|off, default off)
    • timelimit (day|week|month|year)
  • Returns: query, total_results, results[{title, url, body}].
• Resources: duckduckgo://regions — JSON with note, count, and regions[{code, name}] to discover supported region codes.
• Prompts: search_assistant(query, context="") — generates a prompt to analyze search results; research_planner(topic, depth="basic|intermediate|comprehensive") — generates a structured research plan.

Use as CLI Command

Run directly with uvx (no install):

uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-cli "python programming"

Or from this project (or after installing locally) using uv:

uv run duckduckgo-cli "python programming"

With options:

uv run duckduckgo-cli "python programming" \
  --max-results 20 \
  --region us-en \
  --safesearch on \
  --timelimit week \
  --categories text \
  --json

Available options:

• --max-results, -m: Maximum number of results (default: 10)
• --region, -r: Region code (e.g., us-en)
• --safesearch, -s: on, moderate, or off (default: off)
• --timelimit, -t: day, week, month, or year
• --categories, -c: text (default), images, videos, or news
• --json: Output results as JSON array
• --resoure-regions: Print the supported regions resource and exit
• --prompt-search-assistant QUERY: Print the search_assistant prompt text and exit
• --prompt-search-assistant-context CTX: Optional context for search assistant prompt
• --prompt-research-planner TOPIC: Print the research_planner prompt text and exit
• --prompt-research-planner-depth DEPTH: Depth for research planner (basic, intermediate, comprehensive)

Examples with uvx:

# JSON output for scripting
uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-cli \
  "api documentation" --json | jq .

# Generate a prompt for analyzing results
uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-cli \
  --prompt-search-assistant "best python web frameworks" \
  --prompt-search-assistant-context "target: 2025 stack, perf+ecosystem"

# List supported regions (human-readable)
uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-cli --resoure-regions

# List supported regions as JSON
uvx --from git+https://github.com/varlabz/duckduckgo-mcp duckduckgo-cli --resoure-regions --json

# Pin to a branch/tag/commit for reproducibility
uvx --from git+https://github.com/varlabz/duckduckgo-mcp@main duckduckgo-cli "golang tutorials"

Development

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/duckduckgo-mcp.git
3. Set up the development environment:

   cd duckduckgo-mcp
   uv venv
   source .venv/bin/activate
   uv sync
   

Code Quality

• Linting: uv run ruff check
• Formatting: uv run ruff format
• Testing: uv run pytest
• Type checking: Ensure all code follows Python type hints

License

This project is licensed under the MIT License.