# ddgs-mcp

A Model Context Protocol (MCP) server that exposes **DDGS** ([Dux Distributed Global Search](https://github.com/deedy5/ddgs)) — a keyless, multi-engine web metasearch — to AI agents.

It is a drop-in, more reliable alternative to a single SearXNG instance: instead of one upstream that gets IP-banned and poisons every query, DDGS fans each call out over several backends (DuckDuckGo, Bing, Brave, Google, Mojeek, Startpage, Yahoo, Wikipedia, ...) and deduplicates the union. If one engine rate-limits you, the others still answer.

No API key. No account. Runs over stdio via `uvx`, matching the other MCP servers in this stack.

## Install / run

```bash
uvx ddgs-mcp                 # from PyPI (once published)
uvx --from git+https://github.com/marcinkuk/ddgs-mcp.git ddgs-mcp   # direct from git
```

For local development:

```bash
cd ddgs-mcp
uv sync
uv run ddgs-mcp
```

## Tools

| Tool | Purpose |
|---|---|
| `web_search` | General web results (title, url, snippet). |
| `news_search` | News results with source + date. |
| `image_search` | Image results with direct image/thumbnail URLs. |
| `video_search` | Video results with embed URL, duration, publisher. |
| `web_extract` | Read full readable content (markdown) of 1-5 URLs. |
| `search_status` | Diagnostics: version, configured backend/region, per-category backends, live ping. |

Each search tool accepts `backend="auto"` (randomized multi-engine, the default and most resilient) or a specific backend name, plus `region`, `timelimit` (`d`/`w`/`m`/`y`) and `max_results`.

All tools return a uniform envelope `{"ok": bool, "engine": str, "count": int, "results": [...]}`; on failure `ok=false` with a `hint` telling the agent how to retry (e.g. switch to `auto` or a different region).

## Configuration (environment)

| Variable | Default | Meaning |
|---|---|---|
| `DDGS_BACKEND` | `auto` | Default backend for search calls. |
| `DDGS_REGION` | `us-en` | Default region code (`pl-pl`, `de-de`, `wt-wt` ...). |
| `DDGS_TIMEOUT` | `10` | Per-request timeout (seconds). |
| `DDGS_PROXY` | _(unset)_ | Proxy URL passed to DDGS (e.g. `http://127.0.0.1:1080`). Useful behind a rotating proxy to avoid bans. |
| `DDGS_MCP_LOG_LEVEL` | `INFO` | Server log verbosity. |

## Agent Canvas registration

Register with a stdio MCP entry (no secrets required):

```json
{
  "ddgs": {
    "transport": "stdio",
    "command": "uvx",
    "args": ["--from", "git+https://github.com/marcinkuk/ddgs-mcp.git", "ddgs-mcp"],
    "enabled": true,
    "description": "Keyless DDGS metasearch (DuckDuckGo/Bing/Brave/Google) + page extraction. Resilient SearXNG alternative."
  }
}
```

If you want ban-resistance, add an env entry for a rotating proxy:

```json
"env": {"DDGS_PROXY": "http://127.0.0.1:1080"}
```

The value is stored through the normal MCP config path (Fernet-encrypted at rest like the other secrets) — never commit it to this repo.

## Why this over SearXNG?

- **Resilience:** multi-backend aggregation survives single-engine bans (your exact `banuję mnie` symptom).
- **No key / no server:** nothing to host; `uvx` self-heals on container/image upgrades like `trailsearch-mcp`.
- **Extraction:** `web_extract` gives clean markdown of a page in one call.

Keep `searxng` registered alongside it if you like; the two can coexist and you can pick per query.

## License

MIT.