# DuckDuckGo MCP Server 🦆

A fast, free, and unlimited web search MCP server using DuckDuckGo. No API keys required!

[![npm version](https://img.shields.io/npm/v/duckduckgo-mcp.svg)](https://www.npmjs.com/package/duckduckgo-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.0-blue)](https://modelcontextprotocol.io)

## Why This MCP?

- ✅ **100% Free** - No API keys, no subscriptions, no rate limits
- ✅ **Works Everywhere** - DuckDuckGo HTML endpoint bypasses CAPTCHA
- ✅ **3 Powerful Tools** - Search, crawl, and research with AI ranking
- ✅ **Parallel Crawling** - Fetch multiple pages simultaneously
- ✅ **Smart Ranking** - Research tool ranks results by relevance to your question

## Installation

### For Claude Desktop / 100xprompt / Cursor / Windsurf

Add to your MCP config:

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

```json
{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "duckduckgo-mcp"]
    }
  }
}
```

### From Source

```bash
git clone https://github.com/yourusername/duckduckgo-mcp.git
cd duckduckgo-mcp
npm install
npm run build
```

Then add to config:

```json
{
  "mcpServers": {
    "duckduckgo": {
      "command": "node",
      "args": ["/path/to/duckduckgo-mcp/build/index.js"]
    }
  }
}
```

## Tools

### 1. `search`

Quick web search. Returns titles, URLs, and descriptions.

```json
{
  "name": "search",
  "arguments": {
    "query": "latest AI news 2026",
    "count": 10
  }
}
```

**Parameters:**
| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `query` | string | required | - | Search query |
| `count` | number | 10 | 20 | Number of results |

---

### 2. `search_and_crawl`

Search + crawl all result pages in parallel. Get full content from each source.

```json
{
  "name": "search_and_crawl",
  "arguments": {
    "query": "best JavaScript frameworks 2026",
    "count": 5,
    "maxContentLength": 3000
  }
}
```

**Parameters:**
| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `query` | string | required | - | Search query |
| `count` | number | 5 | 10 | Number of results to crawl |
| `maxContentLength` | number | 3000 | 10000 | Max characters per page |

---

### 3. `research` ⭐

Best for answering questions. Searches, crawls in parallel, then **ranks results by relevance** to your question using:

| Scoring Factor       | Weight | Description                                       |
| -------------------- | ------ | ------------------------------------------------- |
| **Keywords**         | 30%    | How many question keywords appear in content      |
| **Content Quality**  | 25%    | Length, structure, no paywalls                    |
| **Source Authority** | 20%    | Domain reputation (Wikipedia=10, Reuters=9, etc.) |
| **Relevance**        | 25%    | Question type matching (how-to, what, why, etc.)  |

```json
{
  "name": "research",
  "arguments": {
    "question": "How does Starlink help Ukraine in the war?",
    "count": 5,
    "maxContentLength": 3000
  }
}
```

**Example Output:**

```
[1] Wikipedia - Score: 6.4/10
    Keywords: 10 | Quality: 5 | Authority: 10 | Relevance: 0.6

[2] Defense Magazine - Score: 5.8/10
    Keywords: 10 | Quality: 7.5 | Authority: 3 | Relevance: 1.2
```

## Usage Examples

### With Claude / 100xprompt

Just ask naturally:

- "Search for the latest news about Tesla"
- "Research how quantum computing works"
- "Find and compare React vs Vue performance"

### Programmatic

```typescript
// Search
const results = await mcp.callTool("search", {
  query: "TypeScript best practices",
  count: 10,
});

// Research with ranking
const research = await mcp.callTool("research", {
  question: "What are the best practices for securing REST APIs?",
  count: 5,
});
```

## How It Works

1. **DuckDuckGo HTML Endpoint** - Uses `html.duckduckgo.com` which returns static HTML
2. **No CAPTCHA** - Unlike Google, DuckDuckGo doesn't block automated requests
3. **Parallel Crawling** - All URLs fetched simultaneously for speed
4. **Smart Extraction** - Removes nav, ads, sidebars; extracts main content

## Source Authority Scores

High-authority domains get better rankings:

| Domain                 | Score |
| ---------------------- | ----- |
| Wikipedia              | 10    |
| Reuters, AP News, BBC  | 9     |
| NYT, WSJ, Bloomberg    | 8     |
| .gov sites             | 8     |
| .edu sites             | 7     |
| TechCrunch, Wired, Ars | 6     |
| Medium, Reddit         | 3-4   |

## Comparison

| Feature            | DuckDuckGo MCP | Tavily      | Google Search API |
| ------------------ | -------------- | ----------- | ----------------- |
| **Free**           | ✅ Yes         | ❌ No       | ❌ No             |
| **API Key**        | ❌ Not needed  | ✅ Required | ✅ Required       |
| **Rate Limits**    | ❌ None        | ✅ Yes      | ✅ Yes            |
| **CAPTCHA Issues** | ❌ No          | ❌ No       | ✅ Yes            |
| **Parallel Crawl** | ✅ Yes         | ✅ Yes      | ❌ No             |
| **Result Ranking** | ✅ Yes         | ✅ Yes      | ❌ No             |

## Limitations

- Some sites block scrapers (403 errors) - this is normal
- Content quality varies by source
- Not suitable for JavaScript-heavy SPA pages

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Test
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search","arguments":{"query":"test"}},"id":1}' | node build/index.js
```

## Contributing

PRs welcome! Ideas:

- Add more authority domains
- Improve content extraction
- Add caching layer
- Support for images/news search

## License

MIT © 2026

## Star History

If you find this useful, please ⭐ star the repo!