# DuckDuckGo Search MCP Server

A Model Context Protocol (MCP) server that provides web search and content fetching capabilities using DuckDuckGo.

## Features

- **Web Search**: Search DuckDuckGo with customizable result limits
- **Content Fetching**: Extract and parse text content from web pages
- **Rate Limiting**: Built-in rate limiting to prevent API abuse
- **Clean Text Extraction**: Removes navigation, scripts, and styling for clean content
- **Dual Transport**: Supports both stdio and streamable-http transports

## Installation

### Standard Installation

```bash
# Clone or download the repository
cd ddg-search-mcp

# Install dependencies
pip install -r src/requirements.txt

# Run the server
python src/server.py
```

### Docker Installation

```bash
# Build the image
docker build -t ddg-search-mcp .

# Run with stdio transport
docker run -i ddg-search-mcp

# Run with HTTP transport
docker run -e MCP_TRANSPORT=streamable-http -p 8000:8000 ddg-search-mcp
```

## Configuration

### Environment Variables

`MCP_TRANSPORT`: Set to `stdio` (default) or `streamable-http` will run http server, port 8000

### Rate Limiting

- Search: 30 requests per minute (default)
- Fetch: 20 requests per minute (default)

Modify the `requests_per_minute` parameter in `server.py` to adjust these limits.

## Tools

### search

Search DuckDuckGo and return formatted results.

**Parameters:**
- `query` (string, required): The search query
- `max_results` (integer, optional): Maximum results to return (default: 10, max: 50)

**Example:**
```json
{
  "query": "python async programming",
  "max_results": 5
}
```

**Returns:**
Formatted search results with title, URL, and snippet for each result.

### fetch_content

Fetch and parse clean text content from a webpage.

**Parameters:**
- `url` (string, required): The webpage URL (must start with http:// or https://)

**Example:**
```json
{
  "url": "https://example.com/article"
}
```

**Returns:**
Cleaned text content from the webpage (max 8000 characters), with scripts, styles, and navigation elements removed.

## Usage with MCP Clients

### Claude Desktop

Add to your Claude Desktop configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "python",
      "args": ["/path/to/src/server.py"]
    }
  }
}
```

### Using Docker with Claude Desktop

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "docker",
      "args": ["run", "-i", "ddg-search-mcp"]
    }
  }
}
```

## Notes

- DuckDuckGo may occasionally block automated requests; the rate limiter helps prevent this
- Fetched content excludes scripts, styles, navigation, headers, and footers
- Maximum content length is 8000 characters per fetch
- All HTTP requests include a standard browser User-Agent