duckduckgo web search with llm-optimized result formatting
Executes web searches against DuckDuckGo's HTML interface and returns formatted results specifically optimized for LLM consumption. The implementation queries DuckDuckGo directly (avoiding API keys), parses HTML responses, removes ad content and redirect URLs, and structures results with titles, URLs, and snippets in a format that LLMs can easily consume and reason about. Rate limiting (30 req/min) prevents service abuse while maintaining responsiveness.
Unique: Uses DuckDuckGo's public HTML interface instead of requiring API keys, with built-in result sanitization (ad removal, redirect URL cleaning) and LLM-specific formatting that strips boilerplate and emphasizes semantic content — implemented as a FastMCP tool with declarative rate limiting
vs alternatives: Eliminates API key management overhead vs Bing/Google Search APIs while providing comparable result quality; faster integration than building custom web scrapers due to MCP protocol standardization
webpage content fetching and html-to-text parsing
Retrieves full webpage content from a given URL and parses HTML into clean, LLM-readable text. The implementation uses HTTP requests to fetch raw HTML, applies HTML parsing and text extraction (removing scripts, styles, navigation elements), and formats the output for optimal LLM consumption. Rate limiting (20 req/min) prevents overwhelming target servers while maintaining throughput for content analysis workflows.
Unique: Implements HTML-to-text conversion optimized for LLM consumption (removes boilerplate, ads, navigation) with built-in rate limiting per tool instance, exposed as a declarative MCP tool rather than a library function — allows LLMs to autonomously decide when to fetch full content vs relying on search snippets
vs alternatives: Simpler integration than Selenium/Playwright for static content (no browser overhead); more LLM-friendly output than raw HTML or markdown converters due to explicit boilerplate removal
mcp tool registration and fastmcp server lifecycle management
Initializes and manages a FastMCP server instance that exposes search and content-fetching tools to MCP-compatible clients. The implementation uses FastMCP's @mcp.tool() decorator pattern to register callable Python functions as remote tools, handles tool invocation routing, manages server lifecycle (startup/shutdown), and provides error handling and logging. The server identifier 'ddg-search' enables client discovery and tool binding.
Unique: Uses FastMCP's declarative @mcp.tool() decorator pattern to eliminate boilerplate MCP protocol handling, with automatic parameter validation and error serialization — allows developers to focus on tool logic rather than protocol implementation details
vs alternatives: Reduces MCP server implementation complexity vs raw MCP SDK by ~70% through decorator-based tool registration; faster to prototype than building custom JSON-RPC servers
per-tool rate limiting with request throttling
Implements independent rate limiting for search (30 req/min) and content-fetching (20 req/min) tools using request throttling. The implementation tracks request timestamps per tool, enforces per-minute quotas, and delays requests that exceed limits to maintain compliance without rejecting calls. Rate limits are applied at the tool invocation layer, ensuring fairness across concurrent LLM clients and preventing service abuse.
Unique: Implements independent per-tool rate limits (30 req/min search, 20 req/min content) with transparent request delay rather than rejection, allowing LLMs to continue operating without error handling logic — rate limits are enforced at the MCP tool invocation layer rather than at HTTP client level
vs alternatives: Simpler than distributed rate limiting (Redis-backed) for single-instance deployments; more user-friendly than hard rejections because LLMs don't need to implement retry logic
html result sanitization and ad/redirect removal
Processes DuckDuckGo search results and fetched webpage content to remove advertisements, tracking redirects, and boilerplate elements. The implementation identifies and strips ad content from search results, cleans DuckDuckGo redirect URLs to expose actual target URLs, removes script/style tags and navigation elements from HTML, and formats remaining content for LLM consumption. This ensures LLMs receive clean, actionable information without noise.
Unique: Implements multi-layer sanitization: removes DuckDuckGo redirect wrappers to expose actual URLs, strips ad content from search results, and removes boilerplate (scripts, styles, navigation) from fetched pages — all applied transparently before returning results to LLM, improving signal-to-noise ratio without requiring LLM-side filtering logic
vs alternatives: More targeted than generic HTML-to-markdown converters because it specifically handles DuckDuckGo redirect URLs and ad patterns; simpler than ML-based content classification while maintaining reasonable accuracy for common cases
claude desktop integration via mcp protocol
Enables the DuckDuckGo MCP server to integrate with Claude Desktop through the Model Context Protocol, allowing Claude to invoke search and content-fetching tools directly. The implementation exposes the FastMCP server over stdio (standard input/output), implements MCP protocol message handling (JSON-RPC), and registers tools in Claude Desktop's configuration. This provides seamless tool access without custom UI or API management.
Unique: Provides native Claude Desktop integration via MCP protocol without requiring custom Claude plugins or API wrappers — tools appear directly in Claude's tool palette and can be invoked conversationally, with results automatically injected into context
vs alternatives: More seamless than building custom Claude plugins because MCP is the standard integration protocol; simpler than API-based integrations because no authentication or rate-limit management is needed on Claude's side
multi-deployment option support (smithery, pip, docker)
Provides multiple installation and deployment pathways for the DuckDuckGo MCP server: Smithery (simplified MCP server registry), pip package installation, and Docker containerization. Each deployment method handles dependency management, environment configuration, and server lifecycle differently, enabling developers to choose based on their infrastructure and operational preferences. Deployment options are documented with setup instructions for each method.
Unique: Offers three distinct deployment paths (Smithery registry, pip package, Docker) with documented setup for each, allowing developers to integrate into existing workflows without forcing a single deployment model — Smithery provides one-click Claude Desktop setup, pip enables local development, Docker enables cloud deployment
vs alternatives: More flexible than single-deployment-method tools; Smithery option reduces setup friction vs manual pip + config file management
comprehensive error handling and result formatting
Implements error handling across search and content-fetching operations with graceful degradation and informative error messages. The implementation catches network errors, parsing failures, rate-limit violations, and malformed inputs, returning structured error responses that LLMs can interpret and act upon. Result formatting ensures consistent output structure (titles, URLs, snippets for search; cleaned text for content) regardless of input variation.
Unique: Implements error handling at the MCP tool layer with formatted error messages that LLMs can interpret and act upon (e.g., 'URL unreachable', 'rate limited'), combined with consistent result formatting (titles + URLs + snippets for search, cleaned text for content) that enables reliable LLM parsing without post-processing
vs alternatives: More LLM-friendly than raw exception propagation because errors are formatted as readable messages; more robust than no error handling because transient failures don't crash the server