Skip to main content
Glama
DuckDuckGo Search MCP

DuckDuckGo Search MCP

by OEvortex
README.md
<div align="center">
  <a href="https://www.npmjs.com/package/@oevortex/ddg_search">
    <img src="https://img.shields.io/npm/v/@oevortex/ddg_search.svg" alt="npm version" />
  </a>
  <a href="https://github.com/OEvortex/ddg_search/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" />
  </a>
  <a href="https://youtube.com/@OEvortex">
    <img src="https://img.shields.io/badge/YouTube-%40OEvortex-red.svg" alt="YouTube Channel" />
  </a>
  <h1>DDG Search</h1>
  <p>
    <strong>Web search and AI-powered answers from the command line or MCP.</strong><br>
    DuckDuckGo, IAsk AI, and Monica AI. No API keys required.
  </p>
</div>

---

## Quick Start

```bash
# Search from the command line
npx -y @oevortex/ddg_search@latest "your search query"

# Or install globally
npm install -g @oevortex/ddg_search
ddg "your search query"
```

## Usage

### CLI

```bash
# Basic web search (DuckDuckGo)
ddg "quantum computing"

# Get more results
ddg "latest news" -n 10

# AI-generated answer (IAsk)
ddg "explain recursion" -m ai

# AI-generated answer (Monica)
ddg "hello world" -m ai -b monica

# IAsk with options
ddg "gravity" -m ai --iask-mode academic --detail-level comprehensive
```

### Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-m, --mode` | `web` or `ai` | `web` |
| `-b, --backend` | `iask` or `monica` (AI mode only) | `iask` |
| `-n, --num-results` | Number of results (1-20, web mode) | `3` |
| `--iask-mode` | `question`, `academic`, `forums`, `wiki`, `thinking` | `thinking` |
| `--detail-level` | `concise`, `detailed`, `comprehensive` | — |
| `-h, --help` | Show help | |
| `-v, --version` | Show version | |

### MCP Server

Start the MCP server for use with Claude Desktop, OpenCode, or other MCP clients:

```bash
ddg --server
```

**Claude Desktop config:**

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "npx",
      "args": ["-y", "@oevortex/ddg_search@latest"]
    }
  }
}
```

**Global install config:**

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "ddg"
    }
  }
}
```

### Programmatic API

```javascript
import { searchDuckDuckGo } from '@oevortex/ddg_search/src/utils/search.js';
import { searchIAsk } from '@oevortex/ddg_search/src/utils/search_iask.js';
import { searchMonica } from '@oevortex/ddg_search/src/utils/search_monica.js';

// DuckDuckGo
const results = await searchDuckDuckGo("query", 5);

// IAsk AI
const answer = await searchIAsk("query", "thinking", null);

// Monica AI
const answer = await searchMonica("query");
```

### MCP Tool Schema

Single unified tool `web-search`:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Search query |
| `mode` | `"web"` \| `"ai"` | `"web"` | DuckDuckGo results or AI answer |
| `backend` | `"iask"` \| `"monica"` | `"iask"` | AI backend (mode=ai only) |
| `numResults` | integer | `3` | Results count (web mode, 1-20) |
| `iaskMode` | string | `"thinking"` | IAsk mode (backend=iask only) |
| `detailLevel` | string | — | IAsk detail level (backend=iask only) |

## Agent Prompt

Add this to your agent's system prompt to enable web search:

```
When you need to search the web or find current information, use the DDG Search CLI:

  npx -y @oevortex/ddg_search@latest "<query>" -m ai

This runs an AI-powered web search via IAsk. For standard DuckDuckGo results (titles + URLs + snippets), use mode "web" instead:

  npx -y @oevortex/ddg_search@latest "<query>" -m web -n 5

For a different AI backend (Monica), add -b monica. Use this for any research, fact-checking, or current events task.
```

## Proxy Support

Respects `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables automatically.

```bash
HTTPS_PROXY=http://proxy:8080 ddg "search query"
```

## Install

```bash
npm install -g @oevortex/ddg_search
```

Or use `npx` without installing.

## Project Structure

```
bin/cli.js              CLI entry point
src/
  index.ts              MCP server
  tools/
    searchTool.js       Unified search tool
  utils/
    search.js           DuckDuckGo scraper
    search_iask.js      IAsk AI client
    search_monica.js    Monica AI client
    user_agents.js      User agent rotation
skills/
  ddg-search/           Agent skill for marketplace
```

## Contributing

Pull requests welcome. Open an issue for bugs or feature requests.

## License

Apache 2.0

---

<div align="center">
  <sub>Made by <a href="https://youtube.com/@OEvortex">@OEvortex</a></sub>
</div>

TDQS

A4/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The two modes are clearly described within the single tool.

Naming Consistency5/5

With a single tool named 'web-search', the naming is self-consistent and follows a clear verb-noun pattern.

Tool Count2/5

A search server with only one tool feels too thin for the domain. Typically, separate tools for different search types (web, images, news, etc.) would be expected.

Completeness2/5

The single tool covers web and AI search but misses common search categories like images, news, and video, leaving notable gaps for typical search use cases.

Maintenance

ActivityNo data
ResponsivenessOutdated data