ddg-image-search
Search and filter web images using keywords, region, size, color, type, layout, license, and time constraints with DuckDuckGo's image search API. Ideal for targeted visual content discovery.
Instructions
Search the web for images using DuckDuckGo
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Image color | |
| keywords | Yes | Search query keywords | |
| layout | No | Image layout | |
| license_image | No | Image license type | |
| max_results | No | Maximum number of results to return | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| size | No | Image size | |
| timelimit | No | Time limit (d=day, w=week, m=month, y=year) | |
| type_image | No | Image type |
Implementation Reference
- src/ddg_mcp/server.py:221-283 (handler)Handler logic for executing the ddg-image-search tool. Extracts arguments, performs image search using DDGS().images(), formats results into interleaved TextContent and ImageContent objects.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)Tool registration including name, description, and input schema definition for ddg-image-search.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)Input schema defining parameters for the ddg-image-search tool, including keywords (required), region, safesearch, etc.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"], },