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)