DuckDuckGo MCP Server

Instructions

This tool performs a web search using DuckDuckGo and returns structured results
including titles, URLs, and body snippets.

Args:
    query: The search query string
    max_results: Maximum number of results to return (1-50)
    region: Region code for localized results (optional)
    safesearch: Safe search filtering level
    timelimit: Time limit for results (day, week, month, year)

Returns:
    SearchResponse with query, results, and total count

Implementation Reference

• src/duckduckgo/mcp.py:134-247 (handler)

  The handler function that executes the 'search' tool logic, performing DuckDuckGo web searches (text, news, images, videos) using the ddgs library and returning structured SearchResponse.

  def search_tool(
      query: str,
      max_results: Annotated[
          int,
          Field(ge=1, le=50, description="Maximum number of results to return (1-50)"),
      ] = 10,
      categories: Annotated[
          Literal["text", "images", "videos", "news"],
          Field(description="Result type to search: text (default), images, videos, or news"),
      ] = "text",
      region: Annotated[
          str | None,
          Field(description="Region code (e.g., 'us-en', 'uk-en', 'de-de')"),
      ] = None,
      safesearch: Annotated[
          Literal["on", "moderate", "off"],
          Field(description="Safe search level"),
      ] = "off",
      timelimit: Annotated[
          Literal["day", "week", "month", "year"] | None,
          Field(description="Time limit for results"),
      ] = None,
  ) -> SearchResponse:
      """Search the web using DuckDuckGo.
  
      This tool performs a web search using DuckDuckGo and returns structured results
      including titles, URLs, and body snippets.
  
      Args:
          query: The search query string
          max_results: Maximum number of results to return (1-50)
          region: Region code for localized results (optional)
          safesearch: Safe search filtering level
          timelimit: Time limit for results (day, week, month, year)
  
      Returns:
          SearchResponse with query, results, and total count
      """
      # map timelimit values to ddgs parameters
      tl = (
          {
              "day": "d",
              "week": "w",
              "month": "m",
              "year": "y",
          }.get(timelimit.strip().lower(), None)
          if timelimit
          else None
      )
      client = DDGS()
      region_param = region or "us-en"
      if categories == "text":
          raw_results = client.text(
              query,
              max_results=max_results,
              region=region_param,
              safesearch=safesearch,
              timelimit=tl,
          )
      elif categories == "news":
          raw_results = client.news(
              query,
              max_results=max_results,
              region=region_param,
              safesearch=safesearch,
              timelimit=tl,
          )
      elif categories == "images":
          raw_results = client.images(
              query,
              max_results=max_results,
              region=region_param,
              safesearch=safesearch,
              timelimit=tl,
          )
          
      elif categories == "videos":
          raw_results = client.videos(
              query,
              max_results=max_results,
              region=region_param,
              safesearch=safesearch,
              timelimit=tl,
          )
      else:
          # Fallback to text in case of unexpected value
          raw_results = client.text(
              query,
              max_results=max_results,
              region=region_param,
              safesearch=safesearch,
              timelimit=tl,
          )
  
      # Convert to structured results
      results: list[SearchResult] = []
      for result in raw_results:
          title = result.get("title", "No title")
          # Prefer common link keys across result types
          url = (
              result.get("href")
              or result.get("url")
              or result.get("content")  # videos
              or result.get("image")  # images direct link
              or "No URL"
          )
          body = (
              result.get("body")
              or result.get("description")  # videos
              or "No body"
          )
          results.append(SearchResult(title=title, url=url, body=body))
  
      return SearchResponse(query=query, results=results, total_results=len(results))

• src/duckduckgo/mcp.py:96-102 (schema)

  Pydantic model defining the output schema of the search tool response.

  class SearchResponse(BaseModel):
      """Response containing search results."""
  
      query: str = Field(description="The search query that was executed")
      results: list[SearchResult] = Field(description="List of search results")
      total_results: int = Field(description="Total number of results returned")

• src/duckduckgo/mcp.py:88-94 (schema)

  Pydantic model defining the schema for individual search results used in the tool output.

  class SearchResult(BaseModel):
      """A single search result from DuckDuckGo."""
  
      title: str = Field(description="The title of the search result")
      url: str = Field(description="The URL of the search result")
      body: str = Field(description="The body/snippet of the search result")

• src/duckduckgo/mcp.py:133-133 (registration)

  FastMCP decorator that registers the search_tool function as the MCP tool named 'search'.

  @mcp.tool(name="search")