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 из панели управления, создаётся бесплатно. Больше ничего. Это удалённый сервер. Не нужно управлять окружением Python, добавлять пакет браузера или держать локальный процесс запущенным.

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

URL сервера одинаков для всех клиентов. Проверено на конфигурациях ниже с Claude Code, Claude Desktop, Cursor, Windsurf и Cline.

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

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

Настройки, затем Коннекторы, затем Добавить пользовательский коннектор, затем вставьте https://mcp.hasdata.com/api/mcp?apis=duckduckgo и войдите.

Для пути через конфигурационный файл добавьте это в claude_desktop_config.json:

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

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

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

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

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

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

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

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

~/.codex/config.toml:

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

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

~/.gemini/settings.json:

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

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

Промпты, а не код. Вставьте один — и агент сам вызовет инструмент. Каждый аннотирован количеством вызовов, потому что в 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, ads, searchAssist и pagination. Органические записи несут position, title, link, displayedLink, source и snippet, плюс дату, сайтлинки и метаданные видео, где DuckDuckGo их показывает. searchAssist содержит собственный AI-ответ DuckDuckGo на запрос.

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

{
  "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, а в теле ответа перечисляются и нераспознанные значения, и все допустимые значения. Если опустить параметр, тот же endpoint откроет доступ ко всем 57 инструментам HasData.

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

Как это сравнивается

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

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

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

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

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

FAQ

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

Нет. DuckDuckGo не публикует MCP-сервер. Каждый вариант создан кем-то другим. Большинство — это open-source проекты, работающие локально, а этот — хостируемый сервер, поддерживаемый 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 могут добавить endpoint как коннектор и войти. Автономные агенты и скрипты используют заголовок 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 при каждом пуше и раз в неделю по расписанию, потому что внешний список инструментов может измениться без участия кого-либо в этом репозитории. Сбой означает, что список инструментов сдвинулся, ключ перестал работать или endpoint был недоступен, и сообщение проверки указывает, что именно.

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

Исправления таблицы параметров и примера ответа — самый полезный вклад, потому что именно эти части расходятся. Приложите выполненный вызов и полученный ответ. Пул-реквесты из форков запускают набор тестов без ключа, а живые проверки пропускаются, а не становятся красными.

Лицензия

MIT. См. LICENSE.