# ddg-mcp MCP server

DuckDuckGo search API MCP - A server that provides DuckDuckGo search capabilities through the Model Context Protocol.

## Components

### Prompts

The server provides the following prompts:
- **search-results-summary**: Creates a summary of DuckDuckGo search results
  - Required "query" argument for the search term
  - Optional "style" argument to control detail level (brief/detailed)

### Tools

The server implements the following DuckDuckGo search tools:

- **ddg-text-search**: Search the web for text results using DuckDuckGo
  - Required: "keywords" - Search query keywords
  - Optional: "region", "safesearch", "timelimit", "max_results"
  
- **ddg-image-search**: Search the web for images using DuckDuckGo
  - Required: "keywords" - Search query keywords
  - Optional: "region", "safesearch", "timelimit", "size", "color", "type_image", "layout", "license_image", "max_results"
  
- **ddg-news-search**: Search for news articles using DuckDuckGo
  - Required: "keywords" - Search query keywords
  - Optional: "region", "safesearch", "timelimit", "max_results"
  
- **ddg-video-search**: Search for videos using DuckDuckGo
  - Required: "keywords" - Search query keywords
  - Optional: "region", "safesearch", "timelimit", "resolution", "duration", "license_videos", "max_results"
  
- **ddg-ai-chat**: Chat with DuckDuckGo AI
  - Required: "keywords" - Message or question to send to the AI
  - Optional: "model" - AI model to use (options: "gpt-4o-mini", "llama-3.3-70b", "claude-3-haiku", "o3-mini", "mistral-small-3")

## Installation

### Prerequisites

- Python 3.9 or higher
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

### Install from PyPI

```bash
# Using uv
uv install ddg-mcp

# Using pip
pip install ddg-mcp
```

### Install from Source

1. Clone the repository:
```bash
git clone https://github.com/misanthropic-ai/ddg-mcp.git
cd ddg-mcp
```

2. Install the package:
```bash
# Using uv
uv install -e .

# Using pip
pip install -e .
```

## Configuration

### Required Dependencies

The server requires the `duckduckgo-search` package, which will be installed automatically when you install `ddg-mcp`.

If you need to install it manually:
```bash
uv install duckduckgo-search
# or
pip install duckduckgo-search
```

## DuckDuckGo Search Parameters

### Common Parameters

These parameters are available for most search types:

- **region**: Region code for localized results (default: "wt-wt")
  - Examples: "us-en" (US English), "uk-en" (UK English), "ru-ru" (Russian)
  - See [DuckDuckGo regions](https://duckduckgo.com/params) for more options

- **safesearch**: Content filtering level (default: "moderate")
  - "on": Strict filtering
  - "moderate": Moderate filtering
  - "off": No filtering

- **timelimit**: Time range for results
  - "d": Last day
  - "w": Last week
  - "m": Last month
  - "y": Last year (not available for news/videos)

- **max_results**: Maximum number of results to return (default: 10)

### Search Operators

You can use these operators in your search keywords:

- `cats dogs`: Results about cats or dogs
- `"cats and dogs"`: Results for exact term "cats and dogs"
- `cats -dogs`: Fewer dogs in results
- `cats +dogs`: More dogs in results
- `cats filetype:pdf`: PDFs about cats (supported: pdf, doc(x), xls(x), ppt(x), html)
- `dogs site:example.com`: Pages about dogs from example.com
- `cats -site:example.com`: Pages about cats, excluding example.com
- `intitle:dogs`: Page title includes the word "dogs"
- `inurl:cats`: Page URL includes the word "cats"

### Image Search Specific Parameters

- **size**: "Small", "Medium", "Large", "Wallpaper"
- **color**: "color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"
- **type_image**: "photo", "clipart", "gif", "transparent", "line"
- **layout**: "Square", "Tall", "Wide"
- **license_image**: "any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"

### Video Search Specific Parameters

- **resolution**: "high", "standard"
- **duration**: "short", "medium", "long"
- **license_videos**: "creativeCommon", "youtube"

### AI Chat Models

- **gpt-4o-mini**: OpenAI's GPT-4o mini model
- **llama-3.3-70b**: Meta's Llama 3.3 70B model
- **claude-3-haiku**: Anthropic's Claude 3 Haiku model
- **o3-mini**: OpenAI's O3 mini model
- **mistral-small-3**: Mistral AI's small model

## Quickstart

### Install

#### Claude Desktop

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

<details>
  <summary>Development/Unpublished Servers Configuration</summary>
  ```
  "mcpServers": {
    "ddg-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/shannon/Workspace/artivus/ddg-mcp",
        "run",
        "ddg-mcp"
      ]
    }
  }
  ```
</details>

<details>
  <summary>Published Servers Configuration</summary>
  ```
  "mcpServers": {
    "ddg-mcp": {
      "command": "uvx",
      "args": [
        "ddg-mcp"
      ]
    }
  }
  ```
</details>

## Usage Examples

### Text Search

```
Use the ddg-text-search tool to search for "climate change solutions"
```

Advanced example:
```
Use the ddg-text-search tool to search for "renewable energy filetype:pdf site:edu" with region "us-en", safesearch "off", timelimit "y", and max_results 20
```

### Image Search

```
Use the ddg-image-search tool to find images of "renewable energy" with color set to "Green"
```

Advanced example:
```
Use the ddg-image-search tool to find images of "mountain landscape" with size "Large", color "Blue", type_image "photo", layout "Wide", and license_image "Public"
```

### News Search

```
Use the ddg-news-search tool to find recent news about "artificial intelligence" from the last day
```

Advanced example:
```
Use the ddg-news-search tool to search for "space exploration" with region "uk-en", timelimit "w", and max_results 15
```

### Video Search

```
Use the ddg-video-search tool to find videos about "machine learning tutorials" with duration set to "medium"
```

Advanced example:
```
Use the ddg-video-search tool to search for "cooking recipes" with resolution "high", duration "short", license_videos "creativeCommon", and max_results 10
```

### AI Chat

```
Use the ddg-ai-chat tool to ask "What are the latest developments in quantum computing?" using the claude-3-haiku model
```

### Search Results Summary

```
Use the search-results-summary prompt with query "space exploration" and style "detailed"
```

## Claude config
"ddg-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/INSTALLATION/ddg-mcp",
        "run",
        "ddg-mcp"
      ]
  },

## Development

### Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:
```bash
uv sync
```

2. Build package distributions:
```bash
uv build
```

This will create source and wheel distributions in the `dist/` directory.

3. Publish to PyPI:
```bash
uv publish
```

Note: You'll need to set PyPI credentials via environment variables or command flags:
- Token: `--token` or `UV_PUBLISH_TOKEN`
- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`

### Automated Publishing with GitHub Actions

This repository includes a GitHub Actions workflow for automated publishing to PyPI. The workflow is triggered when:

1. A new GitHub Release is created
2. The workflow is manually triggered via the GitHub Actions interface

To set up automated publishing:

1. Generate a PyPI API token:
   - Go to https://pypi.org/manage/account/token/
   - Create a new token with scope limited to the `ddg-mcp` project
   - Copy the token value (you'll only see it once)

2. Add the token to your GitHub repository secrets:
   - Go to your repository on GitHub
   - Navigate to Settings > Secrets and variables > Actions
   - Click "New repository secret"
   - Name: `PYPI_API_TOKEN`
   - Value: Paste your PyPI token
   - Click "Add secret"

3. To publish a new version:
   - Update the version number in `pyproject.toml`
   - Create a new release on GitHub or manually trigger the workflow

### Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging
experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).


You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/your/ddg-mcp run ddg-mcp
```


Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.