Dux Distributed Global Search (DDGS)

Install the base library or specific extras for API or MCP server support using pip.

# Base install
pip install -U ddgs

# API server (FastAPI)
pip install -U ddgs[api]

# MCP server (stdio)
pip install -U ddgs[mcp]

The Model Context Protocol (MCP) server allows integration with clients like Cursor or Claude Desktop using stdio transport.

Commands:

• ddgs mcp: Start MCP server.
• ddgs mcp -pr socks5h://127.0.0.1:9150: Start with a proxy.

Available Tools:

• search_text: Web text search
• search_images: Image search
• search_news: News search
• search_videos: Video search
• search_books: Book search
• extract_content: Extract content from a URL

Client Configuration (e.g., Cursor/Claude Desktop):

{
  "mcpServers": {
    "ddgs": {
      "command": "ddgs",
      "args": ["mcp"]
    }
  }
}

You can run ddgs as a Model Context Protocol (MCP) server for local clients like Cursor or Claude Desktop.

Installation:

pip install ddgs[mcp]

Running the server:

• Standard (stdio): ddgs mcp
• With a proxy: ddgs mcp -pr socks5h://127.0.0.1:9150

Client Configuration (JSON):

{
  "mcpServers": {
    "ddgs": {
      "command": "ddgs",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools:

• search_text, search_images, search_news, search_videos, search_books, extract_content.

Proxy Configuration

• Python API: Pass proxy to the DDGS constructor or set the DDGS_PROXY environment variable.
  • DDGS(proxy="socks5h://127.0.0.1:9150")
• MCP Server: Use the -pr flag or set DDGS_PROXY environment variable.
  • ddgs mcp -pr socks5h://127.0.0.1:9150
• CLI: Use the -pr flag or set DDGS_PROXY environment variable.
  • ddgs api -pr socks5h://127.0.0.1:9150

SSL and Timeouts

• SSL Verification: Disable verification with DDGS(verify=False) or provide a path to a certificate with DDGS(verify="/path/to/cert.pem").
• Timeout: Set a custom timeout in seconds with DDGS(timeout=10) (default is 5 seconds).

Use the news() method to perform a news metasearch. It returns a list of dictionaries containing news results.

Arguments:

• query (str): The news search query.
• region (str): Region code (e.g., us-en, uk-en, ru-ru). Defaults to us-en.
• safesearch (str): Filter level (on, moderate, off). Defaults to moderate.
• timelimit (str | None): Time filter (d for day, w for week, m for month). Defaults to None.
• max_results (int | None): Maximum number of results. Defaults to 10.
• page (int): Page number of results. Defaults to 1.
• backend (str): A single or comma-delimited backends. Defaults to auto.

Result Dictionary Keys:

• date
• title
• body
• url
• image
• source

results = DDGS().news(query="sun", region="us-en", safesearch="off", timelimit="m", page=1, backend="auto")
print(results)

Use the books() method to perform a books metasearch. It returns a list of dictionaries containing book information.

Arguments:

• query (str): The book search query.
• max_results (int | None): Maximum number of results. Defaults to 10.
• page (int): Page number of results. Defaults to 1.
• backend (str): A single or comma-delimited backends. Defaults to auto.

Result Dictionary Keys:

• title
• author
• publisher
• info
• url
• thumbnail

results = DDGS().books(query="sea wolf jack london", page=1, backend="auto")
print(results)

Use the extract() method to retrieve content from a specific URL. You can specify the format using the fmt parameter.

Available formats:

• markdown (default): Returns the content as Markdown text in the content key.
• text_plain: Returns plain text.
• content: Returns raw bytes.

Use the extract() method to fetch a URL and convert its content into various formats.

Arguments:

• url (str): The URL to fetch and extract content from.
• fmt (str): The output format. Supported values:
  • text_markdown: HTML to Markdown (preserves links, headers, and lists). Defaults to this.
  • text_plain: HTML to plain text.
  • text_rich: HTML to rich text (includes headers/lists, but removes link URLs).
  • text: Returns raw HTML.
  • content: Returns raw bytes.

Returns: A dictionary containing the url and the extracted content.

# Markdown (default) - preserves links, headers, lists
result = DDGS().extract("https://example.com")

# Plain text
result = DDGS().extract("https://example.com", fmt="text_plain")

# Raw bytes
result = DDGS().extract("https://example.com", fmt="content")

The DDGS class is lazy-loaded and serves as the main entry point for the library. You can configure the HTTP client via the constructor.

Arguments:

• proxy (str, optional): Proxy for the HTTP client (supports http, https, socks5). Example: "http://user:pass@example.com:3128".
• timeout (int, optional): Timeout value for the HTTP client. Defaults to 5.
• verify (bool | str): True to verify, False to skip, or a string path to a PEM file. Defaults to True.

from ddgs import DDGS

results = DDGS().text("python programming", max_results=5)
print(results)

The DDGS class provides methods to perform various types of web searches. All search methods return a list[dict[str, Any]] containing results.

Common search methods include:

• text(query, ...): General web text search.
• images(query, ...): Image search.
• news(query, ...): News search.
• videos(query, ...): Video search.
• books(query, ...): Book search.

Each method supports parameters like max_results, region, safesearch, and backend.

from ddgs import DDGS

# Text search
results = DDGS().text("python async", max_results=5)

# Images, news, videos, books
images = DDGS().images("butterfly", max_results=5)
news   = DDGS().news("ai regulation", timelimit="w")
videos = DDGS().videos("rust programming")
books  = DDGS().books("machine learning")