DuckDuckGo MCP Server

Размещённый сервер Model Context Protocol (MCP), который предоставляет Claude, Cursor, Windsurf и любому другому MCP-клиенту результаты поиска DuckDuckGo в виде структурированного JSON. Ранжированные органические результаты с позициями, реклама в отдельном массиве, собственный AI-ответ DuckDuckGo и 37 регионов для таргетинга. Создан для больших объёмов и для парсинга, без локального браузера и без настройки резервной цепочки.

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

Содержание

• Что вам нужно

• Быстрый старт

• Примеры промптов

• Инструменты

• Ошибки и сценарии сбоев

• Цены, бесплатный тариф и лимиты

• Выбор инструмента

• Сравнение

• FAQ

• Ссылки HasData

• Разработка

• Участие в разработке

• Лицензия

Related MCP server: duckduckgo-mcp

Что вам нужно

MCP-клиент, поддерживающий streamable HTTP с пользовательскими заголовками. Ключ API HasData из панели управления, создаётся бесплатно. Больше ничего. Это удалённый сервер, поэтому самый простой путь — URL и заголовок: не нужно добавлять пакет браузера и поддерживать локальный процесс. Клиент, работающий только со stdio, может вместо этого использовать лаунчер @hasdata/duckduckgo-mcp (npm) или hasdata-duckduckgo-mcp (PyPI).

Быстрый старт

URL сервера одинаков для всех клиентов. Мы используем его в работе в Claude Code и Claude Desktop. Остальные блоки соответствуют документированному формату каждого клиента для удалённого сервера.

Клиенты с поддержкой OAuth могут добавить тот же URL в качестве коннектора и войти, не помещая ключ в конфигурационный файл.

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

Откройте Settings, затем Connectors, затем Add custom connector, затем вставьте https://mcp.hasdata.com/api/mcp?apis=duckduckgo и войдите.

При подходе через файл конфигурации Claude Desktop загружает только локальные (stdio) серверы, поэтому он обращается к удалённому серверу через stdio-лаунчер. Пакет @hasdata/duckduckgo-mcp и есть этот лаунчер, и он читает ключ из переменных окружения. Добавьте это в claude_desktop_config.json:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@hasdata/duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Нужен Python вместо Node? Замените лаунчер на пакет PyPI, который uvx запускает без ручной установки:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "uvx",
      "args": ["hasdata-duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

~/.cursor/mcp.json для всех проектов или .cursor/mcp.json для одного:

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

~/.codeium/windsurf/mcp_config.json. Windsurf называет поле serverUrl, а не url:

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

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

.vscode/mcp.json в рабочей области:

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

~/.codex/config.toml:

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

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

~/.gemini/settings.json:

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

Примеры промптов

Промпты, а не код. Вставьте один — и агент сам вызовет инструмент. Каждый снабжён примечанием о количестве вызовов, потому что в MCP модель сама решает, сколько вызовов сделать, и каждый успешный вызов стоит 10 кредитов.

Найдите в DuckDuckGo «model context protocol» и покажите первые десять результатов с их позициями и доменами.

Один вызов, 10 кредитов.

Выполните запрос «vpn review» в немецком регионе и ещё раз в регионе США, затем скажите, какие домены встречаются в одном, но не в другом.

Два вызова, 20 кредитов. Регион — это параметр. Один и тот же запрос на двух рынках — это два вызова.

Найдите «best crm software» и перечислите только платные размещения, указав домен рекламодателя для каждого.

Один вызов, 10 кредитов. Объявления приходят в отдельном массиве, и никакие эвристики фильтрации не нужны.

Возьмите запрос «model context protocol» и пройдите первые три страницы, затем скажите, какие домены занимают более одной позиции.

Три вызова, 30 кредитов. Каждая страница после первой — новый вызов с курсором; как только курсор получен, уберите q из аргументов.

Найдите «who invented the transistor» и покажите собственный AI-ответ DuckDuckGo рядом с органическими результатами, на которые он опирается.

Один вызов, 10 кредитов.

Две из этих возможностей — причина существования этого сервера. Таргетинг по региону — параметр первого класса на 37 рынках. Сравнение одного запроса по странам — это цикл, а не настройка прокси. Платные размещения возвращаются отдельно от органических, поэтому отслеживание позиций не зависит от догадок, какой результат был рекламой.

Переход на следующую страницу стоит один вызов. Промпт, который проходит десять страниц, — это десять вызовов и 100 кредитов.

Инструменты

Один инструмент. Примеры ниже сокращены из реальных вызовов, и результаты в них меняются по мере изменения веба. Рассматривайте их как описание структуры.

Примеры — это полезная нагрузка, а не весь ответ. Результат tools/call содержит один текстовый блок, и этот текст сам является JSON с полями url, status, text и json; извлечённые данные находятся в json. В необработанном JSON-RPC ответе путь таков: result.content[0].text, затем разбор, затем .json. Чат-клиент разворачивает это за вас, а код, обращающийся к конечной точке напрямую, — нет.

Получение результатов поиска DuckDuckGo

hasdata_duckduckgo_serp_getSearchResults

Получает страницу результатов DuckDuckGo и возвращает её в разобранном виде.

Отправляйте либо q, либо nextPageToken. Если не отправить ни одного, вернётся 422 с указанием обоих полей, потому что требование условное, и схема не может выразить его в виде обычного списка обязательных полей. Отправка обоих не ошибка: выигрывает курсор, а поисковый запрос не выполняется, поэтому агент, который оставляет q в аргументах при перелистывании, молча читает не тот набор результатов.

position отсчитывается внутри страницы, с которой пришёл результат, а не во всём наборе результатов. Вторая страница возвращается с позициями, снова начинающимися с 1, и размер страницы тоже не фиксирован, поэтому встречаются страницы на 10, 15 и 14 результатов. Абсолютный ранг, следовательно, — это число уже собранных органических результатов плюс position, а не то, что можно получить из номера страницы. Постройте набор данных о рангах без этого правила, и каждая страница даст собственную первую позицию.

{
  "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 applications to external systems."
    }
  ],
  "ads": [
    { "position": 1, "title": "Make Agents Accountable", "link": "https://www.gravitee.io/platform/ai-agent-management" }
  ],
  "searchAssist": {
    "answer": "Model Context Protocol (MCP) is an open standard from Anthropic that lets LLMs connect to external tools, systems, and data sources using a shared interface."
  },
  "pagination": { "nextPageToken": "eyJ1cmwiOiJodHRwczovL2xpbmtzLmR1Y2tkdWNrZ28uY29t…" }
}

Ошибки и сценарии сбоев

Ваш клиент почти никогда не видит HTTP-код ошибки от вызова инструмента. Слой MCP отвечает 200 и помещает сбой внутрь результата: isError устанавливается в true, а причина передаётся текстом. Агент читает сообщение там, где вы могли бы ожидать строку статуса.

Неверный ключ проявляется в выводе инструмента, а не в ошибке подключения. Список инструментов принимает любой непустой ключ, поэтому клиент завершает рукопожатие и показывает зелёный статус. Затем первый вызов инструмента возвращается с isError: true и текстом HasData API error: 401 Unauthorized. Следите за этой строкой, потому что ничто раньше в процессе не сообщает о проблеме.

Отсутствующий ключ — единственная настоящая HTTP-ошибка. Авторизация выполняется до любого инструмента, и само подключение завершается ошибкой 401.

Аргумент, нарушающий схему, отклоняется ещё до того, как станет поиском. Сервер отвечает isError: true и текстом MCP error -32602: Input validation error, называя поле. Ничего не извлекается и ничего не списывается.

Если нет ни q, ни nextPageToken, возвращается 422 с массивом errors, в котором названы оба поля и правило requiredIfNotExists, связывающее их.

Запрос, за которым ничего не стоит, всё равно возвращает результаты. DuckDuckGo сам определяет релевантность, поэтому бессмысленная строка возвращается как обычная страница из десяти слабо связанных записей, без ads и searchAssist. Ничто не помечает её как промах, а это важно, если вы строите оповещение о том, что «для этого бренда нет покрытия».

Результаты с данными также содержат requestMetadata.id, который стоит указывать в обращении в поддержку.

Цены, бесплатный тариф и лимиты

Каждый вызов стоит 10 кредитов. Количество результатов не меняет цену. Полная страница стоит столько же, сколько страница с одной записью.

Бесплатный пробный период — 1 000 кредитов на 30 дней без карты, это 100 поисков. После этого активный аккаунт продолжает получать пополнение на 100 кредитов каждый день, когда его баланс опускается ниже 100, поэтому агент с низким объёмом запросов работает на бесплатном тарифе бессрочно.

Платные тарифы начинаются от $49 в месяц за 200 000 кредитов, что соответствует 20 000 поисков. Цена за единицу снижается с объёмом: от $2,45 за 1 000 поисков на начальном тарифе до $0,99 на Business, $0,83 на Growth и $0,75 на самых крупных высокообъёмных тарифах. Актуальные цифры — на странице цен.

Ваш тариф также определяет уровень параллелизма. Бесплатная пробная версия допускает 1 запрос одновременно, Startup — 15, Business — 30, Growth — 50, а высокообъёмные тарифы — от 200 до 1 500. В любом сценарии без присмотра предусмотрительно обрабатывайте случай переполнения, потому что агент, делающий много параллельных вызовов, упрётся в потолок раньше вас.

Запрос, вернувшийся с кодом, отличным от 200, не тарифицируется. Успешный вызов, который ничего не нашёл, всё равно является вызовом.

Выбор инструментов

Параметр запроса apis определяет, какие инструменты видит ваш агент. Чем меньше инструментов, тем меньше контекста уходит на описания инструментов и тем меньше шансов, что модель возьмёт не тот.

?apis=duckduckgo                        the one tool in this repo
?apis=duckduckgo,google_serp            add Google search
?apis=duckduckgo,bing_serp,google_serp  three engines side by side

Параметр принимает имена провайдеров, например duckduckgo, и отдельные имена API, например google_maps_search. Неверно написанные имена игнорируются. Если все имена указаны неверно, запрос завершается ошибкой 400, и в теле ответа перечислены и нераспознанные значения, и все допустимые варианты. Если опустить параметр, та же конечная точка откроет доступ ко всем 57 инструментам HasData.

Три поисковика в одном агенте — частая причина расширить этот список: сравнение одного и того же запроса в DuckDuckGo, Google и Bing превращается в один промпт, как только все три становятся доступны.

Сравнение с альтернативами

Реалистичная альтернатива — сервер, который вы размещаете самостоятельно. Популярные варианты — это Python-пакеты, которые вы запускаете локально: они обращаются к DuckDuckGo с вашей машины и передают модели отформатированный текстовый блок. Это хорошо работает для исследовательского ассистента, отвечающего на один вопрос за раз. Но это перестаёт работать, когда нужны объёмы и стабильная структура.

Две строки в таблице в основном и определяют решение. Текстовый блок — правильный вывод для ответа в чате и неправильный для набора ранжированных данных, потому что восстанавливать position из прозы — работа, которую вам не стоит делать. А то, что получение страниц — наше, снимает вопрос бэкенда: не нужно выбирать между httpx и клиентом, имитирующим браузер, устанавливать дополнительный пакет, от которого зависит запасной вариант, и читать трассировку стека, когда обычный HTTP-клиент перестаёт получать страницу.

Всё остальное в этом списке — реальный компромисс. Самостоятельно размещённый сервер бесплатен, не требует аккаунта, оставляет ваши запросы на вашей машине и извлекает содержимое страниц — чего этот сервер не делает. Если вы выполняете несколько поисков в день внутри одного ассистента, он подходит лучше. Этот сервер — для случаев, когда начинает иметь значение количество поисков, количество регионов или форма вывода.

В отличие от собственного API DuckDuckGo. api.duckduckgo.com — это Instant Answer API: он возвращает энциклопедическую справку, если она существует, а не страницу результатов. Официального эндпоинта, который отдавал бы ранжированные веб-результаты, не существует — поэтому все варианты здесь парсят страницу.

Чего этот сервер не делает. Никакого получения страниц или извлечения содержимого, никаких вертикалей изображений или новостей, никакого автодополнения. Он возвращает страницу результатов в разобранном виде.

Часто задаваемые вопросы

Существует ли официальный MCP-сервер DuckDuckGo?

Нет. DuckDuckGo не публикует MCP-сервер. Каждый вариант создан кем-то другим. Большинство — это проекты с открытым исходным кодом, работающие локально, а этот — размещённый сервер, поддерживаемый HasData.

Что такое MCP-сервер DuckDuckGo?

Это сервер, который предоставляет поиск DuckDuckGo как инструмент, который может вызывать AI-клиент. Клиент отправляет вызов инструмента по протоколу Model Context Protocol, сервер выполняет поиск и возвращает структурированный JSON, а модель работает с результатом и никогда не видит HTML-страницу.

Нужны ли мне аккаунт DuckDuckGo или API-ключ?

Нет. Единственные учётные данные — ваш ключ HasData. У DuckDuckGo нет программы для разработчиков, в которой можно зарегистрироваться, а публикуемый им Instant Answer API не возвращает результатов поиска.

Нужно ли мне что-то размещать или запускать?

Нет. Это удалённый MCP-сервер на streamable HTTP. Устанавливать нечего: ни среды Python, ни пакета браузера, ни процесса, который нужно перезапускать.

Данные живые или кэшируются?

Живые. Каждый вызов получает страницу результатов в момент запроса и несёт собственный requestMetadata.id. Два одинаковых вызова — это две отдельные загрузки, а не воспроизведение сохранённой копии.

Можно ли сравнивать один и тот же запрос в разных регионах?

Да, и это главная причина использовать параметр вместо прокси. kl принимает 37 кодов регионов, а cc вместе с setLang разделяют страну и язык, когда их нужно развести. Каждый регион — отдельный вызов.

Что произойдёт, когда DuckDuckGo изменит свою вёрстку?

На вашей стороне ничего не изменится. Мы отслеживаем изменения и сохраняем стабильной схему ответа, так что имена и типы полей остаются на месте. Блок, которому нечего сообщить, отсутствует в ответе, поэтому читайте ads и searchAssist со значением по умолчанию.

Можно ли использовать это вместе с другими API HasData?

Да. Параметр apis принимает список, а ?apis=duckduckgo,google_serp,bing_serp даёт вашему агенту сразу три поисковых движка.

Можно ли войти через OAuth вместо вставки ключа?

Да, в клиентах, которые это поддерживают. Claude Desktop и Cursor могут добавить эндпоинт как коннектор и выполнить вход. Автономные агенты и скрипты используют заголовок x-api-key.

Соответствие требованиям и персональные данные

HasData обращается только к общедоступным данным. Условия платформы могут ограничивать автоматический доступ, и вы сами отвечаете за соблюдение требований. Если собираемые вами данные содержат личную информацию, убедитесь, что у вас есть законное основание для их обработки в соответствии с GDPR, CCPA или аналогичными правилами в вашей юрисдикции.

Ссылки HasData

Разработка

Этот репозиторий — конфигурация и документация для удалённого сервера. Здесь нет шага сборки и нечего контейнеризировать.

Тесты в test/ проверяют контракт инструментов — ту часть, которая может сломаться даже без изменений в этом репозитории. Они проверяют, что ?apis=duckduckgo возвращает ровно один инструмент, что его имя не изменилось, что описанные в этом README параметры по-прежнему существуют с перечисленными в нём enum-значениями и что используемый ключ действительно принимается. Последняя проверка выполняет реальный поиск и стоит 10 кредитов — это цена канарейки, которая может упасть по правильной причине.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

Тот же набор тестов запускается в CI при каждом пуше и раз в неделю по расписанию, потому что внешний список инструментов может измениться, даже если никто не трогает этот репозиторий. Сбой означает, что список инструментов изменился, ключ перестал работать или эндпоинт был недоступен, и в сообщении проверки сказано, что именно.

Участие в разработке

Полезнее всего — исправления в таблице параметров и примере ответа, потому что именно эти части устаревают. Прикладывайте сделанный вами вызов и полученный ответ. Pull Request из форков запускают набор тестов без ключа, а «живые» проверки пропускаются, а не падают с ошибкой.

Лицензия

MIT. См. LICENSE.