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