DuckDuckGo Browser Server

A production-ready Model Context Protocol (MCP) server that performs real-time internet searches via the DuckDuckGo Lite endpoint (https://lite.duckduckgo.com/lite/) with automatic retry logic, intelligent caching, and robust error handling.

Supports all three MCP transports:

• stdio — for MCP desktop hosts and IDE plugins
• SSE — Server-Sent Events over HTTP
• streamable-http — chunked HTTP streaming (default for container deployment)

---

Folder Structure

duckduckgo-tool/
├── duckduckgo_server.py             # Main MCP server entry point
├── pyproject.toml
├── Dockerfile
├── README.md
├── pytest.ini
├── tests/
│   ├── __init__.py
│   └── test_search_tools.py
└── src/
    └── duckduckgo_browser/
        ├── __init__.py
        ├── __main__.py              # python -m duckduckgo_browser
        ├── duckduckgo_server.py     # stub (canonical server is at root)
        ├── services/
        │   ├── __init__.py
        │   ├── search_engine.py     # RealSearchEngine — DuckDuckGo Lite
        │   └── web_scraper.py       # DuckDuckGoScraper with retry & cache
        └── tools/
            ├── __init__.py
            ├── toolhandler.py       # Abstract base class
            └── search_tools.py     # get_internet_result tool handler

---

Available Tool (1)

get_internet_result

Performs a real-time search on DuckDuckGo Lite and returns a concise answer with source links.

Parameter	Type	Required	Description
input_value	string	✅	Natural language query or search term

Example output:

Answer: Machine learning is a branch of artificial intelligence that enables systems to learn
        and improve from experience without being explicitly programmed.
Source 1: https://www.ibm.com/topics/machine-learning
Source 2: https://www.google.com/search?q=what+is+machine+learning

---

Local Setup

# Create and activate virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# Install dependencies
pip install -e .

Dependencies:

• mcp[cli] >= 1.12.0
• starlette >= 0.27.0
• uvicorn >= 0.20.0
• requests >= 2.31.0
• beautifulsoup4 >= 4.12.0
• truststore >= 0.10.0

---

Run

The server is controlled by environment variables or CLI flags. Environment variables take priority and are used for container deployments.

Environment Variable	Default	Description
TRANSPORT_TYPE	streamable-http	Transport mode: stdio, sse, streamable-http
APP_HOST	0.0.0.0	Bind host
APP_PORT	8000	Bind port

stdio (default for MCP desktop hosts)

duckduckgo-mcp --mode stdio

SSE

duckduckgo-mcp --mode sse --host 0.0.0.0 --port 8000

Endpoints:

• GET /sse — open SSE stream
• POST /messages/ — send MCP request frames
• GET /health — health check
• GET /healthz — health check (alias)
• GET / — server info

Streamable HTTP

duckduckgo-mcp --mode streamable-http --host 0.0.0.0 --port 8000

Endpoints:

• POST /mcp — single MCP endpoint, chunked streaming response
• GET /health — health check
• GET /healthz — health check (alias)
• GET / — server info

---

Docker

# Build
docker build -t duckduckgo-mcp .

# Run streamable-http (default)
docker run -p 8000:8000 duckduckgo-mcp

# Run SSE mode
docker run -e TRANSPORT_TYPE=sse -e APP_PORT=8000 -p 8000:8000 duckduckgo-mcp

# Run with custom port
docker run -e TRANSPORT_TYPE=streamable-http -e APP_PORT=9000 -p 9000:9000 duckduckgo-mcp

# Run stdio mode (pipe-based)
docker run -i -e TRANSPORT_TYPE=stdio duckduckgo-mcp

---

MCP Client Configuration

Streamable HTTP

{
  "mcpServers": {
    "duckduckgo": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE

{
  "mcpServers": {
    "duckduckgo": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio

{
  "mcpServers": {
    "duckduckgo": {
      "command": "duckduckgo-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

---

Testing with MCP Inspector

Streamable HTTP:

1. Start the server: duckduckgo-mcp --mode streamable-http --port 8000
2. Open MCP Inspector and connect to: http://localhost:8000/mcp
3. Call get_internet_result with {"input_value": "what is machine learning"}

SSE:

1. Start the server: duckduckgo-mcp --mode sse --port 8000
2. Open MCP Inspector and connect to: http://localhost:8000/sse
3. Call get_internet_result with {"input_value": "best cloud providers 2026"}

---

How It Works

Search Flow

User Query
    ↓
get_internet_result (async tool handler)
    ↓
RealSearchEngine.search()
    ↓
DuckDuckGoScraper.search_with_retry()
    ├─ Check in-memory cache (5-min TTL)
    ├─ Cache hit  → return cached results
    └─ Cache miss → fetch from DuckDuckGo Lite
        ├─ Attempt 1 (10s timeout)
        ├─ Fail → wait 2s → Attempt 2
        ├─ Fail → wait 4s → Attempt 3
        └─ All fail → return stale cache or empty result
    ↓
Auto-detect category from result content
    ↓
Format: Answer + Source 1 + Source 2

Key Features

Feature	Details
Search Source	DuckDuckGo Lite (https://lite.duckduckgo.com/lite/) with HTML + Instant Answer API fallback
Retry Logic	3 attempts with exponential backoff (2s, 4s)
Request Timeout	10 seconds per attempt
Caching	In-memory, 5-min TTL, stale fallback on network failure
SSL	OS trust store via truststore; falls back to SSL-disabled as last resort
CORS	Fully open (allow_origins=["*"]) for all HTTP modes
Session Timeout	60s per request (streamable-http), unlimited (stdio)

Category Detection

Results are automatically categorised from URL, title, and snippet content:

ai · programming · cloud · finance · health · science · education · travel · food · sports · general

---

Kubernetes Deployment

For EC2/Kubernetes, set transport mode and port via environment variables — no image rebuild needed:

# Streamable HTTP deployment
env:
  - name: TRANSPORT_TYPE
    value: "streamable-http"
  - name: APP_PORT
    value: "8000"
  - name: APP_HOST
    value: "0.0.0.0"

# SSE deployment
env:
  - name: TRANSPORT_TYPE
    value: "sse"
  - name: APP_PORT
    value: "8000"
  - name: APP_HOST
    value: "0.0.0.0"

No supergateway wrapper is needed. The server handles its own HTTP binding directly for both SSE and streamable-http modes.

---

Running Tests

pip install pytest pytest-asyncio
pytest

---

Troubleshooting

Port already in use

duckduckgo-mcp --mode streamable-http --port 8001

No search results returned

• Verify internet connectivity from the host/container
• Test: curl "https://lite.duckduckgo.com/lite/?q=test"
• Enable debug logging:

  PYTHONPATH=src python -c "import logging; logging.basicConfig(level=logging.DEBUG)"
  

SSL errors in corporate network

• The scraper automatically retries with SSL verification disabled as a last resort
• Alternatively, set verify_ssl=False in web_scraper.py DuckDuckGoScraper init

Import errors after install

pip install -e . --force-reinstall

---

Configuration Reference

Tune scraper behaviour in src/duckduckgo_browser/services/web_scraper.py:

DuckDuckGoScraper(
    timeout=10.0,           # Request timeout per attempt (seconds)
    max_retries=3,          # Number of retry attempts
    retry_backoff_base=2.0, # Exponential backoff base (2s, 4s, ...)
    cache_ttl=300,          # Cache TTL in seconds (5 minutes)
)

---

Robustness Summary

Scenario	Behaviour
Network timeout	Retry up to 3x with exponential backoff
All retries fail	Return stale cache if available, else empty result
DuckDuckGo Lite unavailable	Fall back to HTML endpoint, then Instant Answer API
SSL certificate error	Retry with SSL verification disabled
Invalid query	Validation error returned as TextContent
Port conflict	Clear error log with suggested fix
Container restart	Cache cleared (in-memory); fresh searches on next request

---

Requirements

• Python 3.10+
• Internet access (for DuckDuckGo searches)
• No API key required

License

MIT License — see LICENSE file for details