duckduckgo-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Model Context Protocol (MCP) server providing DuckDuckGo web search and webpage content fetching. Built with Python using the FastMCP framework. Published to PyPI as duckduckgo-mcp-server.

Commands

# Install dependencies
uv sync

# Run the server
uv run duckduckgo-mcp-server

# Run with MCP Inspector (for interactive testing)
mcp dev src/duckduckgo_mcp_server/server.py

# Run all tests (unit + e2e)
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e MCP protocol tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

# Run a single test
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py::TestRateLimiter::test_acquire_removes_expired_entries

# Build package
uv build

# Lint (ruff) — matches the CI `quality` job
uv run ruff check .

# Audit dependencies for known vulnerabilities (informational)
uv run --with pip-audit pip-audit --desc

Architecture

Single-module server in src/duckduckgo_mcp_server/server.py with three main classes:

• DuckDuckGoSearcher — Scrapes DuckDuckGo's HTML endpoint (html.duckduckgo.com/html) via POST requests. Parses results with BeautifulSoup. Handles SafeSearch (kp param) and region (kl param) configuration.
• WebContentFetcher — Fetches arbitrary URLs, strips non-content elements (script, style, nav, header, footer), and returns cleaned text truncated to 8000 chars.
• RateLimiter — Sliding-window rate limiter (30 req/min for search, 20 req/min for content fetching).

Two MCP tools are exposed: search and fetch_content.

Configuration

Environment variables read at startup (not per-request):

• DDG_SAFE_SEARCH: STRICT | MODERATE (default) | OFF
• DDG_REGION: Region code like us-en, cn-zh, jp-ja, wt-wt
• DDG_ALLOW_PRIVATE_URLS: 1/true to let fetch_content reach loopback/private/link-local/metadata addresses (default off — SSRF guard). Also settable via --allow-private-urls.
• DDG_SEARCH_BACKEND: auto (default) | httpx | curl — HTTP backend for the search tool. auto falls back to curl_cffi Chrome TLS impersonation when DuckDuckGo returns a fingerprint block (HTTP 202/403); curl/fallback need the [browser] extra. Also settable via --search-backend.
• DDG_ALLOWED_HOSTS / DDG_ALLOWED_ORIGINS: comma-separated Host/Origin allow-lists for the HTTP transports (DNS-rebinding protection). Needed behind a reverse proxy / in Docker to avoid 421 Misdirected Request. Values must include the port if the client sends one (host:* accepts any port); there is no bare * — use --disable-dns-rebinding-protection (DDG_DISABLE_DNS_REBINDING_PROTECTION) to accept any host. _build_transport_security() merges the SDK's localhost patterns into whatever is configured, since passing explicit settings to FastMCP otherwise replaces its localhost default wholesale. Also --allowed-hosts / --allowed-origins.
• TRANSPORT / HOST / PORT: fallbacks for --transport / --host / --port, for container platforms (Rancher, k8s) where Arguments are hard to set. Deliberately not DDG_-prefixed. TRANSPORT accepts a single value or a comma-separated list (sse,streamable-http); an invalid value errors at startup. Resolved in main() after parse_args(), so a CLI flag always wins and HOST/PORT alone never breaks stdio mode.
• DDG_JSON_RESPONSE: 1/true makes streamable-http POST replies a single application/json body instead of an SSE stream (--json-response). Set via mcp.settings.json_response before mcp.streamable_http_app() — FastMCP caches the session manager on first call. For blocking HTTP clients that cannot read chunked multi-event streams.
• DDG_DISABLE_PROGRESS_NOTIFICATIONS: 1/true routes ctx.info/ctx.error to the module logger instead of the MCP wire, via the _log_info() / _log_error() helpers that wrap all 20 call sites. Read per call, so tests toggle it with patch.dict(os.environ, ...).
• DDG_CA_CERTS: path to a PEM CA bundle for verifying TLS on outbound requests (needed behind TLS-intercepting proxies — httpx no longer reads SSL_CERT_FILE). DDG_SSL_VERIFY=0 disables verification entirely (discouraged). Also --ca-certs / --no-ssl-verify. Applies to all four client sites (httpx + curl_cffi, search + fetch).