Agent skill

ddgs

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.

View SKILL.md on GitHub Repository
Stars 2,441
Forks 237

Install this agent skill to your Project

npx add-skill https://github.com/deedy5/ddgs/tree/main/skills/ddgs

SKILL.md

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

python
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

bash
# 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:

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

MCP Server

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

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

Client configuration:

json
{
  "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, 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)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

sickn33/antigravity-awesome-skills

obsidian-clipper-template-creator

Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.

28,421 4,766
Explore
sickn33/antigravity-awesome-skills

claude-code-expert

Especialista profundo em Claude Code - CLI da Anthropic. Maximiza produtividade com atalhos, hooks, MCPs, configuracoes avancadas, workflows, CLAUDE.md, memoria, sub-agentes, permissoes e integracao com ecossistemas.

28,421 4,766
Explore
sickn33/antigravity-awesome-skills

lex

Centralized 'Truth Engine' for cross-jurisdictional legal context (US, EU, CA) and contract scaffolding.

28,421 4,766
Explore
sickn33/antigravity-awesome-skills

odoo-inventory-optimizer

Expert guide for Odoo Inventory: stock valuation (FIFO/AVCO), reordering rules, putaway strategies, routes, and multi-warehouse configuration.

28,421 4,766
Explore
sickn33/antigravity-awesome-skills

android_ui_verification

Automated end-to-end UI testing and verification on an Android Emulator using ADB.

28,421 4,766
Explore
sickn33/antigravity-awesome-skills

seo-cannibalization-detector

Analyzes multiple provided pages to identify keyword overlap and potential cannibalization issues. Suggests differentiation strategies. Use PROACTIVELY when reviewing similar content.

28,421 4,766
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results