{
"markdown": "# Яндекс Вордстат MCP\n\n[](https://www.npmjs.com/package/mcp-yandex-wordstat)\n[](https://github.com/askads/mcp-yandex-wordstat/actions/workflows/ci.yml)\n[](https://glama.ai/mcp/servers/askads/mcp-yandex-wordstat)\n[](./LICENSE)\n\n**Яндекс Вордстат MCP** подключает AI-приложение к статистике поискового спроса Яндекса. Спросите, как часто ищут фразу, в какие месяцы интерес растёт и в каких городах тема популярнее, — ассистент соберёт данные Вордстата и объяснит результат. Сервер работает через Yandex Cloud Search API, поэтому не требует доступа к рекламному кабинету Директа.\n\n- **Пять инструментов.** Топ и похожие запросы, динамика спроса, распределение по регионам, справочник регионов и технический запрос к API.\n- **Только чтение.** API Вордстата не создаёт кампании, объявления, ключевые фразы и другие объекты.\n- **Спрос и сезонность.** Топ запросов и регионы показывают последние 30 дней; динамика строится по дням, неделям или месяцам за нужный период.\n- **Регион и устройство.** Отчёты можно сузить до региона и сравнить спрос на компьютерах, телефонах и планшетах.\n- **Без OAuth Директа.** Нужны API-ключ и ID каталога Yandex Cloud для Search API.\n\nНачните с безопасного запроса:\n\n> Сколько в месяц ищут «купить велосипед» и какие есть похожие запросы?\n\n[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)\n\n---\n\n## Увидеть работу за минуту\n\n![\"Демонстрация:](\"docs/demo.gif\")
\n\n## Содержание\n\n- [Быстрый старт](#быстрый-старт)\n- [Что можно поручить](#что-можно-поручить)\n- [Как читать данные спроса](#как-читать-данные-спроса)\n- [Как получить доступ](#как-получить-доступ)\n- [Что может изменить данные](#что-может-изменить-данные)\n- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)\n- [Техническая документация](#техническая-документация)\n- [Поддержка](#поддержка)\n\n## Быстрый старт\n\nНужны Node.js 20 или новее, API-ключ Yandex Cloud для Search API и ID каталога Yandex Cloud.\n\n1. [Получите доступ](#как-получить-доступ) и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.\n2. Спросите: «Сколько в месяц ищут „купить велосипед“ и какие есть похожие запросы?»\n\n\nCodex
\n\n
\n\n**Через интерфейс приложения:**\n\n1. Откройте **Settings → Plugins → MCP servers**.\n2. Нажмите **Add server**.\n3. Добавьте команду запуска `npx -y mcp-yandex-wordstat@latest` и переменные окружения `WORDSTAT_API_KEY`, `WORDSTAT_FOLDER_ID`.\n\n**Через командную строку:**\n\n```bash\ncodex mcp add yandex-wordstat \\\n --env WORDSTAT_API_KEY=ваш_ключ \\\n --env WORDSTAT_FOLDER_ID=ваш_folder_id \\\n -- npx -y mcp-yandex-wordstat@latest\n```\n\nПроверьте подключение:\n\n```bash\ncodex mcp list\n```\n\n[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)\n\n \n\n\nClaude Code
\n\n
\n\n```bash\nclaude mcp add \\\n --env WORDSTAT_API_KEY=ваш_ключ \\\n --env WORDSTAT_FOLDER_ID=ваш_folder_id \\\n --transport stdio \\\n --scope user \\\n yandex-wordstat \\\n -- npx -y mcp-yandex-wordstat@latest\n```\n\nПроверьте сервер:\n\n```bash\nclaude mcp list\n```\n\n[Документация Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)\n\n \n\n\nClaude Desktop
\n\n
\n\nОткройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"yandex-wordstat\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-yandex-wordstat@latest\"],\n \"env\": {\n \"WORDSTAT_API_KEY\": \"ваш_ключ\",\n \"WORDSTAT_FOLDER_ID\": \"ваш_folder_id\"\n }\n }\n }\n}\n```\n\nЕсли **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\\Claude\\claude_desktop_config.json` на Windows.\n\n \n\n\nCursor
\n\n
\n\nДля всех проектов создайте `~/.cursor/mcp.json`; только для текущего проекта — `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"yandex-wordstat\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-yandex-wordstat@latest\"],\n \"env\": {\n \"WORDSTAT_API_KEY\": \"ваш_ключ\",\n \"WORDSTAT_FOLDER_ID\": \"ваш_folder_id\"\n }\n }\n }\n}\n```\n\n[Документация Cursor](https://docs.cursor.com/context/model-context-protocol)\n\n \n\n\nVS Code
\n\n
\n\nОткройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`:\n\n```json\n{\n \"servers\": {\n \"yandex-wordstat\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-yandex-wordstat@latest\"],\n \"env\": {\n \"WORDSTAT_API_KEY\": \"${input:wordstat_api_key}\",\n \"WORDSTAT_FOLDER_ID\": \"${input:wordstat_folder_id}\"\n }\n }\n },\n \"inputs\": [\n {\n \"type\": \"promptString\",\n \"id\": \"wordstat_api_key\",\n \"description\": \"API-ключ Yandex Cloud\",\n \"password\": true\n },\n {\n \"type\": \"promptString\",\n \"id\": \"wordstat_folder_id\",\n \"description\": \"ID каталога Yandex Cloud\"\n }\n ]\n}\n```\n\nПроверьте запуск командой **MCP: List Servers**.\n\n[Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n \n\n## Что можно поручить\n\n### Подобрать и оценить спрос\n\n- «Сколько раз за месяц ищут эту фразу и какие похожие запросы встречаются?»\n- «Подбери запросы вокруг „доставка пиццы“ с их частотностью».\n- «Покажи запросы, содержащие мою фразу, отдельно от семантически похожих».\n\n### Понять сезонность\n\n- «Покажи спрос на „лыжи“ по месяцам за год».\n- «В какие недели спрос на эту услугу растёт или падает?»\n- «Сравни динамику запроса на телефонах и компьютерах».\n\n### Сравнить регионы\n\n- «В каких городах интерес к „ремонту квартир“ выше среднего?»\n- «Сравни спрос в Москве и Санкт-Петербурге».\n- «Найди ID нужного региона и сузь следующий отчёт до него».\n\n## Как читать данные спроса\n\n`top_requests` показывает популярные запросы, которые содержат заданную фразу, и семантически близкие запросы. Общий `totalCount` относится к последним 30 дням.\n\n`dynamics` возвращает ряд `{date, count, share}` с дневной, недельной или месячной детализацией. `regions` распределяет спрос за последние 30 дней по регионам, а `affinityIndex` выше 100% означает интерес выше среднего. Значения счётчиков могут приходить строками: Яндекс передаёт большие целые числа в JSON в таком виде.\n\nОдин вызов строит данные только для одной фразы. Для большого списка ключевых слов лучше сначала сузить список, а не запускать все запросы подряд: квота Yandex Cloud Search API общая для одного ключа.\n\n## Как получить доступ\n\n1. В Yandex Cloud создайте сервисный аккаунт с ролью `search-api.webSearch.user`.\n2. Выпустите для него API-ключ со scope `yc.search-api.execute` — шаги описаны в [документации AI Studio](https://yandex.cloud/ru/docs/ai-studio/operations/get-api-key).\n3. Найдите ID каталога (`folderId`) в [консоли Yandex Cloud](https://console.yandex.cloud/) на странице каталога и в URL страницы.\n4. Передайте ключ как `WORDSTAT_API_KEY`, а каталог как `WORDSTAT_FOLDER_ID`.\n\nСервер обращается к Yandex Cloud Search API v2. Старый отдельный Wordstat API с OAuth не используется. API-ключ хранится в конфигурации MCP-клиента открытым текстом — относитесь к нему как к паролю.\n\n## Что может изменить данные\n\nНичего в Яндекс Вордстате. Все пять инструментов, включая `raw_request`, работают только на чтение. Технически API использует `POST`, но у Wordstat нет эндпоинтов на запись; сервер дополнительно не позволяет произвольному запросу уйти на другой хост.\n\n## Данные, лимиты и работа в фоне\n\n- **Агрегированные данные.** Сервер получает статистику поискового спроса, а не данные конкретного рекламного кабинета.\n- **Кэш справочника регионов.** В долгоживущем процессе дерево регионов загружается один раз и переиспользуется в следующих запросах.\n- **Повторы при временных ошибках.** Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов после `429`, `5xx`, сетевой ошибки или тайм-аута; учитывает `Retry-After`, а задержка не превышает 30 секунд.\n- **Нет фонового наблюдения.** Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический отчёт по выбранным фразам.\n- **Анонимная телеметрия.** По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. В неё не попадают API-ключ, аргументы инструментов, ваши сообщения, данные спроса и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: `ASKADS_TELEMETRY=0`.\n\n## Техническая документация\n\n- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.\n- [Все инструменты и параметры](./docs/TOOLS.md)\n- [Документация по разработке](./docs/DEVELOPMENT.md)\n- [Документация по публикации](./docs/PUBLISHING.md)\n- [Документация Yandex Cloud Search API](https://yandex.cloud/ru/docs/search-api/)\n\n## Поддержка\n\nНашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-yandex-wordstat/issues) или напишите в [Telegram](http://t.me/gistrec).\n",
"bytes": 9604,
"sha": "2ab88a38b7a9117c288d7e76fd02c8998e93f829c7dd35583b6d92be13456013",
"repo_slug": "askads/mcp-yandex-wordstat",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_askads_mcp_yandex_wordstat_ed5682ff/readme"
}