/ddgs

name: ddgs
description: Use when an agent needs to search the web, find images/news/videos/books, or extract content from a URL. Covers the ddgs Python library, CLI, and MCP server integration.

ddgs — Web Search for Agents

Overview

**ddgs** (Dux Distributed Global Search) is a Python metasearch library that aggregates results from multiple search engines. Agents can use it via Python API, CLI, or MCP server.

Python API

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")

# Extract content from a URL
page = DDGS().extract("https://example.com")
page["content"]  # Markdown text (default)
page = DDGS().extract("https://example.com", fmt="text_plain")
page = DDGS().extract("https://example.com", fmt="content")  # raw bytes

All search methods return `list[dict[str, Any]]`. Each dict has keys depending on category:

| Method | Keys | |--------|------| | `text()` | `title`, `href`, `body` | | `images()` | `title`, `image`, `thumbnail`, `url`, `height`, `width`, `source` | | `videos()` | `title`, `content`, `description`, `duration`, `embed_url`, `images`, `publisher` | | `news()` | `date`, `title`, `body`, `url`, `image`, `source` | | `books()` | `title`, `author`, `publisher`, `info`, `url`, `thumbnail` |

CLI

# Text search
ddgs text -q "python async" --max_results 5

# Other categories
ddgs images -q "cats" --color Blue
ddgs news -q "tech" --timelimit d
ddgs videos -q "cars" --duration medium
ddgs books -q "sea wolf"

# Extract content
ddgs extract -u https://example.com
ddgs extract -u https://example.com -f text_plain

# Save results
ddgs text -q "dogs" -o results.json
ddgs text -q "dogs" -o results.csv

# Version
ddgs version

CLI for Agents

Agents can also use `ddgs` as a CLI tool via subprocess. Auto-detects non-TTY — outputs plain text without colors or interactive pauses.

To discover available options:

ddgs --help
ddgs text --help
ddgs images --help

MCP Server

stdio (for local MCP clients like Cursor, Claude Desktop)

pip install ddgs[mcp]
ddgs mcp                             # stdio MCP server
ddgs mcp -pr socks5h://127.0.0.1:9150  # with proxy

Client configuration:

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

Available MCP Tools

| Tool | Description | |------|-------------| | `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 |

Quick Reference

| Parameter | Values | Default | |-----------|--------|---------| | `region` | `us-en`, `uk-en`, `ru-ru`, `de-de`, etc. | `us-en` | | `safesearch` | `on`, `moderate`, `off` | `moderate` | | `timelimit` | `d` (day), `w` (week), `m` (month), `y` (year) | None | | `max_results` | int | 10 | | `page` | int | 1 | | `backend` | `auto`, `all`, or engine name | `auto` |

Available backends by method:

| Method | Backends | |--------|----------| | `text()` | `bing`, `brave`, `duckduckgo`, `google`, `grokipedia`, `mojeek`, `startpage`, `yandex`, `yahoo`, `wikipedia` | | `images()` | `bing`, `duckduckgo` | | `videos()` | `duckduckgo` | | `news()` | `bing`, `duckduckgo`, `yahoo` | | `books()` | `annasarchive` |

Tips

• **Proxy (Python)**: `DDGS(proxy="socks5h://127.0.0.1:9150")` or set env `DDGS_PROXY`
• **Proxy (MCP)**: `ddgs mcp -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`
• **Proxy (API)**: `ddgs api -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`
• **SSL verification**: `DDGS(verify=False)` or `DDGS(verify="/path/to/cert.pem")`
• **Timeout**: `DDGS(timeout=10)` (default: 5 seconds)
• **Errors**: catches `DDGSException`, `RatelimitException`, `TimeoutException`
• **Multiple backends**: `backend="bing,google"` (comma-separated)