ddg-image-search
Search for images on the web using DuckDuckGo with filters for size, color, type, license, and time limits.
Instructions
Search the web for images using DuckDuckGo
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Search query keywords | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| timelimit | No | Time limit (d=day, w=week, m=month, y=year) | |
| size | No | Image size | |
| color | No | Image color | |
| type_image | No | Image type | |
| layout | No | Image layout | |
| license_image | No | Image license type | |
| max_results | No | Maximum number of results to return |
Implementation Reference
- src/ddg_mcp/server.py:221-283 (handler)The handler logic for the 'ddg-image-search' tool within the @server.call_tool() function. It parses input arguments, performs an image search using DuckDuckGo's DDGS.images(), processes the results, and returns interleaved text descriptions and image contents.elif name == "ddg-image-search": keywords = arguments.get("keywords") if not keywords: raise ValueError("Missing keywords") region = arguments.get("region", "wt-wt") safesearch = arguments.get("safesearch", "moderate") timelimit = arguments.get("timelimit") size = arguments.get("size") color = arguments.get("color") type_image = arguments.get("type_image") layout = arguments.get("layout") license_image = arguments.get("license_image") max_results = arguments.get("max_results", 10) # Perform search ddgs = DDGS() results = ddgs.images( keywords=keywords, region=region, safesearch=safesearch, timelimit=timelimit, size=size, color=color, type_image=type_image, layout=layout, license_image=license_image, max_results=max_results ) # Format results formatted_results = f"Image search results for '{keywords}':\n\n" text_results = [] image_results = [] for i, result in enumerate(results, 1): text_results.append( types.TextContent( type="text", text=f"{i}. {result.get('title', 'No title')}\n" f" Source: {result.get('source', 'Unknown')}\n" f" URL: {result.get('url', 'No URL')}\n" f" Size: {result.get('width', 'N/A')}x{result.get('height', 'N/A')}\n" ) ) image_url = result.get('image') if image_url: image_results.append( types.ImageContent( type="image", url=image_url, alt_text=result.get('title', 'Image search result') ) ) # Interleave text and image results combined_results = [] for text, image in zip(text_results, image_results): combined_results.extend([text, image]) return combined_results
- src/ddg_mcp/server.py:108-127 (registration)Registration of the 'ddg-image-search' tool in the @server.list_tools() function, including its name, description, and detailed JSON schema for input parameters.types.Tool( name="ddg-image-search", description="Search the web for images using DuckDuckGo", inputSchema={ "type": "object", "properties": { "keywords": {"type": "string", "description": "Search query keywords"}, "region": {"type": "string", "description": "Region code (e.g., wt-wt, us-en, uk-en)", "default": "wt-wt"}, "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "description": "Safe search level", "default": "moderate"}, "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "description": "Time limit (d=day, w=week, m=month, y=year)"}, "size": {"type": "string", "enum": ["Small", "Medium", "Large", "Wallpaper"], "description": "Image size"}, "color": {"type": "string", "enum": ["color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"], "description": "Image color"}, "type_image": {"type": "string", "enum": ["photo", "clipart", "gif", "transparent", "line"], "description": "Image type"}, "layout": {"type": "string", "enum": ["Square", "Tall", "Wide"], "description": "Image layout"}, "license_image": {"type": "string", "enum": ["any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"], "description": "Image license type"}, "max_results": {"type": "integer", "description": "Maximum number of results to return", "default": 10}, }, "required": ["keywords"], }, ),
- src/ddg_mcp/server.py:111-126 (schema)JSON schema defining the input parameters for the 'ddg-image-search' tool, including required 'keywords' and various optional filters.inputSchema={ "type": "object", "properties": { "keywords": {"type": "string", "description": "Search query keywords"}, "region": {"type": "string", "description": "Region code (e.g., wt-wt, us-en, uk-en)", "default": "wt-wt"}, "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "description": "Safe search level", "default": "moderate"}, "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "description": "Time limit (d=day, w=week, m=month, y=year)"}, "size": {"type": "string", "enum": ["Small", "Medium", "Large", "Wallpaper"], "description": "Image size"}, "color": {"type": "string", "enum": ["color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"], "description": "Image color"}, "type_image": {"type": "string", "enum": ["photo", "clipart", "gif", "transparent", "line"], "description": "Image type"}, "layout": {"type": "string", "enum": ["Square", "Tall", "Wide"], "description": "Image layout"}, "license_image": {"type": "string", "enum": ["any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"], "description": "Image license type"}, "max_results": {"type": "integer", "description": "Maximum number of results to return", "default": 10}, }, "required": ["keywords"], },