barysiuk/ddgs-search-mcp

DDGS Search MCP Server

A local Model Context Protocol (MCP) server that provides text search capabilities using the Dux Distributed Global Search (ddgs) library. This server allows AI agents (like Claude) to perform web searches by aggregating results from diverse web search services.

Features

• Text Search: Perform web searches via DDGS metasearch.
• Configurable: Settings like region, safe search, max results, proxy, and retries are configurable via settings.yaml.
• Local Execution: Runs locally on your machine using a Python virtual environment.
• Stdio Transport: Communicates via standard input/output (STDIN/STDOUT) using the official mcp SDK.
• Resilient: Built-in retry mechanism with configurable delays to handle network issues and rate limits.

Prerequisites

• Python 3.10 or higher (Tested with 3.13).

Installation

1. Clone or Navigate to the directory: Ensure you are in the project directory.

2. Create a Virtual Environment (if you want to isolate it):

   python3 -m venv .venv
   

3. Install Dependencies:

   source .venv/bin/activate
   pip install -r requirements.txt
   

Configuration

You can configure the default search behavior by editing the settings.yaml file in the main directory.

max_results: 10       # Default number of results to return
region: "us-en"       # Search region (e.g., us-en, uk-en, ru-ru)
safesearch: "moderate" # Safe search level: on, moderate, off
backend: "auto"       # Backend to use: auto, html, lite, api

# Anti-bot / Network settings
proxy: null           # e.g., "http://user:pass@example.com:3128"
timeout: 10           # Request timeout in seconds
retries: 3            # Number of retries on failure
delay: 2.0            # Delay between retries in seconds

Usage with Claude for Desktop

To use this MCP server with Claude for Desktop, you need to add it to your configuration file.

1. Locate the Config File:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit the Config File: Add the ddgs-search server to the mcpServers object. Important: You must use absolute paths for both the python executable and the server.py script.

   Run pwd in your terminal to find the absolute path to the current directory.

   {
     "mcpServers": {
       "ddgs-search": {
         "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/.venv/bin/python",
         "args": [
           "/ABSOLUTE/PATH/TO/YOUR/PROJECT/server.py"
         ]
       }
     }
   }
   

   Replace /ABSOLUTE/PATH/TO/YOUR/PROJECT with the actual path to this directory.

3. Restart Claude: Restart the Claude Desktop application. The "search" tool should now be available to Claude.

Troubleshooting

403 Forbidden Errors / Rate Limits

If you are seeing "403 Forbidden" errors, it likely means the search provider has blocked your request (often due to IP reputation or rate limiting).

Solutions:

1. Use a Proxy: Edit settings.yaml and set the proxy value.

   proxy: "socks5://127.0.0.1:9050" # Example for Tor or local proxy
   

2. Increase Delays: Increase the delay setting in settings.yaml to wait longer between retries.
3. Increase Retries: Increase retries to try more times before giving up.

Development

To test the server manually, you can use the mcp CLI inspector (if installed) or run it directly and interact via stdin/stdout if you know the protocol.