Metadata-Version: 2.4
Name: ddg-search-mcp
Version: 0.1.3
Summary: A free, unlimited web search MCP server for LLM agents using DuckDuckGo
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4
Requires-Dist: fastmcp
Requires-Dist: httpx
Requires-Dist: mcp
Requires-Dist: trafilatura
Description-Content-Type: text/markdown

# DuckDuckGo Search MCP Server

A free, unlimited web search MCP server for LLM agents. Uses DuckDuckGo to search the web and returns full extracted page content.


## How it works

1. Your LLM agent calls the `web_search` tool with a query
2. The server searches DuckDuckGo and gets the top results
3. It concurrently fetches each result page and extracts the main content, stripping ads, navigation, and boilerplate
4. Clean, structured Markdown is returned — ready for the LLM to reason over and cite

Results are sorted with full page extracts first, falling back to snippets for pages that can't be fetched (paywalls, bot blocks, etc.). A summary header tells the agent how many full extracts vs snippets were returned.

---

## Requirements

- [Claude desktop app](https://claude.ai/download)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed

---

## Installation

```bash
claude mcp add web-search uvx ddg-search-mcp
```

That's it. No virtual environments, no pip installs, no API keys. `uvx` handles everything automatically in an isolated environment.

Verify it's connected:

```bash
claude mcp list
```

You should see `web-search` with a ✓ connected status.

---

## Usage

Once installed, just talk to Claude naturally:

> *"Search for the latest news on AI regulation"*

> *"Find recent benchmarks comparing Claude and GPT-4"*

> *"Look up how to configure a Next.js app router"*

Claude will automatically call the `web_search` tool when it needs current information from the web.

You can also explicitly ask:

> *"Use web search to find..."*

### Tool parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Natural language search query |
| `num_results` | int | 5 | Number of results to fetch (1–10) |

---

## Performance

- Pages are fetched **concurrently** — 5 results take roughly the same time as 1
- Pages that take longer than **8 seconds** are dropped automatically
- Known bot-blocking domains (YouTube, Twitter, Reddit, LinkedIn, etc.) are skipped to avoid wasting time
- DuckDuckGo **lite endpoint** is used as primary, with the HTML endpoint as fallback

---

## Privacy

All searches go through DuckDuckGo, which does not track users or build profiles. No data is sent to any third-party API.

---

## Limitations

- Results depend on DuckDuckGo's index — not Google
- Some sites block automated fetching (paywalls, Cloudflare protection) and will fall back to snippet-only
- DuckDuckGo may throttle very high-frequency automated requests

---

## Updating

```bash
uv cache clean
claude mcp remove web-search
claude mcp add web-search uvx ddg-search-mcp
```

---

## License

MIT