duckduckgo-mcp

# DuckDuckGo MCP Server

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client DuckDuckGo search results as structured JSON. Ranked organic results with positions, ads in their own array, DuckDuckGo's own AI answer, and 37 regions to target. Built for volume and for parsing, with no local browser and no fallback chain to configure.

```
https://mcp.hasdata.com/api/mcp?apis=duckduckgo
```

[![tool contract](https://github.com/HasData/duckduckgo-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/duckduckgo-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Regions](https://img.shields.io/badge/regions-37-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=duckduckgo-mcp), free to create. Nothing else. This is a remote server. There is no Python environment to manage, no browser package to add and no local process that has to stay up.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=duckduckgo` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http duckduckgo "https://mcp.hasdata.com/api/mcp?apis=duckduckgo" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=duckduckgo` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so a remote server is reached through the `mcp-remote` bridge, which needs Node. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
        "--header",
        "x-api-key:HASDATA_API_KEY"
      ]
    }
  }
}
```

The `x-api-key:` value carries no space after the colon. Claude Desktop passes the argument without a shell, and a space splits the header.

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "duckduckgo": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

```json
{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "duckduckgo": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Codex CLI</b></summary>

`~/.codex/config.toml`:

```toml
[mcp_servers.duckduckgo]
url = "https://mcp.hasdata.com/api/mcp?apis=duckduckgo"

[mcp_servers.duckduckgo.headers]
"x-api-key" = "HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "duckduckgo": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent calls the tool itself. Each is annotated with the calls it takes, because in MCP the model decides how many calls to make and every successful call costs 10 credits.

> Search DuckDuckGo for "model context protocol" and give me the top ten results with their positions and domains.

*One call, 10 credits.*

> Run the query "vpn review" in the German region and again in the US region, then tell me which domains appear in one and not the other.

*Two calls, 20 credits. Region is a parameter. The same query in two markets is two calls.*

> Search for "best crm software" and list only the paid placements, with the advertiser domain for each.

*One call, 10 credits. Ads arrive in their own array and need no filtering heuristics.*

> Take the query "model context protocol" and walk the first three pages, then tell me which domains hold more than one position.

*Three calls, 30 credits. Each page after the first is a fresh call with the cursor, and drop `q` from the arguments once you have one.*

> Search "who invented the transistor" and show me DuckDuckGo's own AI answer next to the organic results it drew on.

*One call, 10 credits.*

Two of those are the reason this server exists. Region targeting is a first-class parameter across 37 markets. Comparing one query across countries is a loop and not a proxy setup. And paid placements come back separately from organic, which keeps rank tracking from depending on guessing which result was an ad.

Paging costs a call each time. A prompt that walks ten pages is ten calls and 100 credits.

## Tools

One tool. Samples below are trimmed from real calls, and the results in them change as the web changes. Read them as shapes.

The samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Get DuckDuckGo search results

[`hasdata_duckduckgo_serp_getSearchResults`](https://docs.hasdata.com/apis/duckduckgo/serp?utm_source=github&utm_medium=syndication&utm_campaign=duckduckgo-mcp)

Fetches a DuckDuckGo results page and returns it parsed.

| Parameter | Type | Notes |
| :--- | :--- | :--- |
| `q` | string | The search term. Either `q` or `nextPageToken` has to be present |
| `nextPageToken` | string | Cursor from `pagination.nextPageToken` in the previous response. Wins if you send both, and the `q` you sent alongside it is ignored without a warning |
| `kl` | string | Region as `<country>-<language>`, 37 values from `us-en` and `de-de` to `jp-jp` and `wt-wt` for no region |
| `cc` | string | Two-letter country, 36 values. An alternative to `kl` when paired with `setLang` |
| `setLang` | string | Interface and result language, 33 values |
| `safeSearch` | string | `off`, `moderate` or `strict` |
| `deviceType` | string | `desktop`, `mobile` or `tablet` |

> Send either `q` or `nextPageToken`. Sending neither returns 422 naming both fields, because the requirement is conditional and the schema cannot express it as a plain required list. Sending both is not an error either, the cursor wins and the query goes nowhere, so an agent that keeps `q` in the arguments while paging silently reads the wrong result set.

> `position` counts inside the page it came from, not across the whole result set. Page two comes back with positions starting at 1 again, and page size is not fixed either, so pages of 10, 15 and 14 results all turn up. Absolute rank is therefore the number of organic results you have already collected plus `position`, not anything you can derive from the page number. Build a rank dataset without that and every page contributes its own number one.

Returns `organicResults`, `ads`, `searchAssist` and `pagination`. Organic entries carry `position`, `title`, `link`, `displayedLink`, `source` and `snippet`, plus a date, sitelinks and video metadata where DuckDuckGo shows them. `searchAssist` holds DuckDuckGo's own AI answer for the query.

> `ads` and `searchAssist` are absent when the page has neither, so test for the key before reading it. `organicResults` can be absent too, so read it with a default rather than treating its presence as given. A query with no real matches still comes back as a full page of loosely related entries, which is not how "nothing found" usually looks.

```json
{
  "organicResults": [
    {
      "position": 1,
      "title": "What is the Model Context Protocol (MCP)?",
      "link": "https://modelcontextprotocol.io/docs/getting-started/intro",
      "displayedLink": "modelcontextprotocol.io › docs › getting-started › intro",
      "source": "modelcontextprotocol.io",
      "snippet": "MCP is an open-source standard for connecting AI applicat