Yandex Wordstat MCP Server

Yandex Wordstat MCP 服务

非官方开源 MCP 服务，为 AI Agent 提供对 Yandex Wordstat API 所有标准方法的类型化只读访问权限。

状态：0.1.0，首个公开版本。

英文

功能

• Wordstat API 的全部四种方法，以及按名称本地搜索地区 ID 的附加功能；
• 严格的输入和输出架构、安全的自动日期范围以及运算符验证；
• 根据 Retry-After 重试临时错误，并支持超时和请求取消；
• 本地 RPS、每小时请求数和并发数限制；
• 地区树缓存、同时请求去重，以及回退到过期缓存；
• API 调用、HTTP 尝试次数和估算计费调用次数的计数器；
• stdio 传输，不向协议 stdout 写入日志。

所有工具均标记为只读且幂等。Wordstat 请求属于外部 API 调用，并且可能产生费用。

要求和访问权限

• Node.js 22.23.4+、24.22.1+ 或 26.12.1+，且属于相应的 LTS 系列；
• 具有 yc.search-api.execute scope 的 API 密钥 或 IAM 令牌；
• Yandex Cloud 相应目录上的 search-api.webSearch.user 角色。

在 MCP 客户端的环境中设置且仅设置一种凭据：

export YANDEX_WORDSTAT_API_KEY='your-api-key'
# или: export YANDEX_WORDSTAT_IAM_TOKEN='your-iam-token'

请勿将真实凭据保存在代码库或共享的 MCP 配置中。更改客户端环境后，请重启客户端。

何时需要 YANDEX_WORDSTAT_FOLDER_ID

对于 Yandex 账户或联合账户的 IAM 令牌，此变量为必填项。请指定分配了 search-api.webSearch.user 角色的目录 ID：

export YANDEX_WORDSTAT_FOLDER_ID='b1g...'

对于 API 密钥或服务账户的 IAM 令牌，通常无需设置此变量：Search API 会使用服务账户的目录。

连接到 MCP 客户端

请选择一种授权方式：API 密钥 或 IAM 令牌。请勿同时传入两者。Codex 和 Claude Code 示例中的变量已导出到客户端进程的环境中。

Codex CLI / IDE

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.yandex-wordstat]
command = "npx"
args = ["-y", "wordstat-mcp-server@latest"]
env_vars = ["YANDEX_WORDSTAT_API_KEY"]

对于 Yandex 账户或联合账户的 IAM 令牌，请使用：

[mcp_servers.yandex-wordstat]
command = "npx"
args = ["-y", "wordstat-mcp-server@latest"]
env_vars = ["YANDEX_WORDSTAT_IAM_TOKEN", "YANDEX_WORDSTAT_FOLDER_ID"]

然后运行 codex mcp list 检查连接。Codex CLI 和 IDE 使用相同的配置。

Claude Code

claude mcp add-json --scope user yandex-wordstat \
  '{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_API_KEY":"${YANDEX_WORDSTAT_API_KEY}"}}'
claude mcp list

Yandex 账户或联合账户的 IAM 令牌配置：

claude mcp add-json --scope user yandex-wordstat \
  '{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_IAM_TOKEN":"${YANDEX_WORDSTAT_IAM_TOKEN}","YANDEX_WORDSTAT_FOLDER_ID":"${YANDEX_WORDSTAT_FOLDER_ID}"}}'
claude mcp list

Hermes Agent

将服务添加到用户级 ~/.hermes/config.yaml：

mcp_servers:
  yandex_wordstat:
    command: "npx"
    args: ["-y", "wordstat-mcp-server@latest"]
    env:
      YANDEX_WORDSTAT_API_KEY: "your-api-key"

Yandex 账户或联合账户的 IAM 令牌配置：

mcp_servers:
  yandex_wordstat:
    command: "npx"
    args: ["-y", "wordstat-mcp-server@latest"]
    env:
      YANDEX_WORDSTAT_IAM_TOKEN: "your-iam-token"
      YANDEX_WORDSTAT_FOLDER_ID: "your-folder-id"

Hermes 只会向 stdio 服务传递明确列出的变量。请勿将含有凭据的用户配置添加到代码库。

运行 hermes mcp test yandex_wordstat 检查连接，然后重启 Hermes 或执行 /reload-mcp。工具将以 mcp_yandex_wordstat_ 为前缀注册。并行调用默认处于关闭状态，有助于控制配额。

Инструменты

Инструмент	Назначение	Важные параметры
wordstat_top_requests	Популярные и связанные запросы за последние 30 дней	phrase, num_phrases 1–2000, region_ids, devices
wordstat_dynamics	Дневная, недельная или месячная динамика	phrase, period, from_date, to_date, auto_dates, фильтры
wordstat_regions	Частота, доля и affinity index по регионам за последние 30 дней	phrase, region_type, limit, offset, resolve_names
wordstat_regions_tree	Иерархия поддерживаемых регионов	max_depth 1–20, root_region_id
wordstat_find_regions	Локальный поиск ID региона по названию	query, limit, parent_region_id, include_children

Значения devices: all, desktop, phone, tablet; all нельзя сочетать с другими значениями. В одном запросе допускается до 100 region_ids.

wordstat_find_regions работает по кэшированному дереву. Он полезен, когда агент знает название региона, но не его ID. wordstat_regions при resolve_names: true делает дополнительный бесплатный вызов дерева только при промахе кэша. Каждая следующая страница wordstat_regions заново вызывает платный метод распределения по регионам, поэтому для полной выборки лучше использовать максимальный limit.

Даты и операторы

wordstat_dynamics принимает даты в формате YYYY-MM-DD. Если при auto_dates: true обе даты отсутствуют, сервер запрашивает последние 60 завершённых дней, 52 завершённые недели или 12 завершённых месяцев — в зависимости от детализации. Если отсутствует только одна граница, сервер вычисляет её; автоматически добавленный to_date всегда указывает на последний завершённый период. Явно переданные границы не сдвигаются. При auto_dates: false обязателен только from_date; to_date можно не задавать.

Дневной диапазон не может превышать 60 дней. Для недельной и месячной детализации Wordstat документирует диапазон от 3 недель или месяцев до 5 лет; самая ранняя доступная история начинается с января 2018 года. Неделя задаётся от понедельника до воскресенья, месяц — от первого до последнего дня месяца.

Для дневной динамики разрешены операторы -, !, +, кавычки, [], () и |; для недельной и месячной — только +. Явные неподдерживаемые операторы для недельной и месячной детализации отклоняются до платного API-вызова.

Метаданные результата

Каждый успешный ответ содержит:

• api_calls — логические вызовы Wordstat API, включая бесплатное дерево регионов;
• http_attempts — все HTTP-попытки, в том числе повторы;
• billable_calls_estimate — оценка платных вызовов; финальный биллинг определяет Yandex;
• local_hourly_budget_remaining — остаток локального часового лимита или null;
• content_truncated — был ли сокращён текстовый MCP-контент из-за размера.

Поля count и total_count возвращаются строками, чтобы не терять точность 64-битных целых.

Примеры запросов агенту

Расширение семантики

Подбери запросы по теме «онлайн-курсы английского». Покажи 100 популярных запросов
и похожие запросы за последний месяц. Сгруппируй их по смыслу: обучение, цена,
формат, уровень и бренды. В каждой группе выдели 5 самых популярных фраз.
Популярные и похожие запросы покажи отдельно.

Сравнение регионального спроса

Сравни спрос на «доставка цветов» в Москве и Санкт-Петербурге за последние 12 полных
месяцев. Найди нужные регионы сам. Покажи динамику по месяцам для каждого города,
отметь месяцы с самым высоким и низким спросом и объясни различия в сезонности.
Если каких-то данных нет, не додумывай их.

Интерес по регионам

Покажи, в каких регионах запросом «горнолыжный курорт» интересуются сильнее всего.
Составь два списка: топ-15 регионов по индексу интереса и топ-15 по числу запросов.
Для каждого региона укажи число запросов, долю и индекс интереса. Коротко объясни,
почему списки отличаются. Загружай дополнительные страницы только при необходимости.

Сезонность и сравнение с прошлым годом

Проанализируй спрос на «кондиционер» по России за последние 24 полных календарных месяца,
не включая текущий месяц. Используй регион «Россия» с ID 225 и обязательно задай начало
и конец периода. Сравни каждый месяц с тем же месяцем годом ранее. Покажи изменение
в запросах и процентах, а также начало и пик сезона. Если данных не хватает, перечисли
пропущенные месяцы и сравни только полные пары. Если год назад было ноль запросов,
процентное изменение не рассчитывай.

Различия по устройствам

Сравни спрос на «заказать продукты» с компьютеров, телефонов и планшетов за последние
60 полных дней. Для каждого типа устройства покажи общее число запросов, среднее за день
и его долю среди трёх типов устройств. Сравнивай только даты, которые есть во всех выборках.
Не называй число запросов количеством уникальных пользователей.

Влияние операторов Wordstat

Покажи, как кавычки влияют на статистику запроса «ремонт квартир». Сравни за последние
60 полных дней обычный запрос `ремонт квартир` и запрос в кавычках `"ремонт квартир"`.
Покажи общую частотность каждого варианта, разницу между ними и простыми словами
объясни, что ограничивают кавычки в Wordstat.

Контроль стоимости исследования

Нужно изучить запрос «ипотека»: популярные и похожие запросы, динамику по месяцам
и интерес по регионам. Сначала скажи, сколько платных обращений к Wordstat потребуется,
и дождись моего подтверждения. После исследования покажи фактическое число обращений
и отдельно отметь повторные попытки, если они были.

配置

变量	默认值	允许的值
YANDEX_WORDSTAT_API_KEY	—	两种凭据中必须且只能设置一种
YANDEX_WORDSTAT_IAM_TOKEN	—	两种凭据中必须且只能设置一种
YANDEX_WORDSTAT_FOLDER_ID	—	最多 50 个字符；参见上文条件
YANDEX_WORDSTAT_TIMEOUT_MS	30000	1–300000
YANDEX_WORDSTAT_MAX_RETRIES	2	0–10
YANDEX_WORDSTAT_MAX_RPS	8	1–10000
YANDEX_WORDSTAT_MAX_RPH	100	0–1000000；0 表示不限制
YANDEX_WORDSTAT_MAX_CONCURRENCY	4	1–100
YANDEX_WORDSTAT_REGIONS_CACHE_TTL_MS	86400000	0–2592000000
YANDEX_WORDSTAT_LOG_LEVEL	error	silent、error、warn、info、debug

进程级限制可防止意外消耗，但不会在多个进程之间同步，也不能替代 Yandex Cloud 配额。重试会计入 http_attempts，但一次逻辑调用只占用一个本地 RPH 配额单位。

错误和诊断

工具错误包含 code、安全的 message、retryable，以及（如有）http_status、 retry_after_seconds 和 http_attempts。

症状	检查内容
CONFIGURATION_ERROR	是否恰好设置了一种凭据；数值是否在允许范围内
HTTP 400 / VALIDATION_ERROR	短语、日期、时段、运算符、区域 ID 和文件夹 ID
HTTP 401 / AUTHENTICATION_ERROR	凭据是否有效；环境变量更改后是否重启了 MCP 客户端
HTTP 403 / AUTHORIZATION_ERROR	是否已将 search-api.webSearch.user 角色分配给所需目录
HTTP 429 / RATE_LIMITED	降低 RPS／并发量，或等待 retry_after_seconds
TIMEOUT / NETWORK_ERROR	网络、API 访问权限和 YANDEX_WORDSTAT_TIMEOUT_MS
动态数据为空	是否请求了已完成且可用的时段，以及正确的区域筛选条件

日志仅写入 stderr。如需诊断，可暂时设置 YANDEX_WORDSTAT_LOG_LEVEL=debug； 服务不会记录凭据和 Authorization 标头。

本地开发

npm install
npm run build
YANDEX_WORDSTAT_API_KEY='...' node dist/cli.js

无需访问 Wordstat API 的检查：

npm run check
npm test
npm run smoke:package

Live probe 和 live smoke 可能消耗配额，且需要凭据。只有在明确执行 npm run contract:probe 和 npm run smoke:live:mcp 时才会运行。

安全

服务不会修改数据，只会访问 Wordstat API。不过，回复中的短语和名称来自外部来源：Agent 应将其视为不可信内容，而不是指令。 请按照 SECURITY.md 中的规则报告漏洞，不要通过公开 issue 报告。

许可证

MIT

---

英语

非官方开源 MCP 服务，为 AI Agent 提供对所有标准 Yandex Wordstat API 方法的类型化只读访问权限。

状态：0.1.0，首次公开发布。

功能

• 提供全部四种 Wordstat 方法，以及本地地区名称查询，方便 Agent 查找 ID；
• 严格的架构、日期／运算符验证、重试、超时和取消机制；
• 本地 RPS、每小时调用次数和并发限制；
• 共享的地区树缓存，并支持进行中的请求去重和缓存过期时回退；
• 每个结果均提供 API 调用次数、HTTP 尝试次数和预估计费调用次数；
• 保持 stdio 传输整洁：协议仅使用 stdout，诊断信息仅使用 stderr。

所有工具均为只读且幂等。Wordstat 请求属于外部 API 调用，且可能产生费用。

要求和凭据

• 对应 LTS 版本线中的 Node.js 22.23.4+、24.22.1+ 或 26.12.1+；
• 具有 yc.search-api.execute 范围的 API 密钥或 IAM 令牌；
• 目标 Yandex Cloud 文件夹中具有 search-api.webSearch.user 角色。

在 MCP 客户端的环境中设置且仅设置一种凭据：

export YANDEX_WORDSTAT_API_KEY='your-api-key'
# or: export YANDEX_WORDSTAT_IAM_TOKEN='your-iam-token'

使用 Yandex 账户或联合账户 IAM 令牌时，必须设置 YANDEX_WORDSTAT_FOLDER_ID。将其设为授予该角色的文件夹 ID。使用 API 密钥或服务账户 IAM 令牌时，通常可以省略此变量，因为 Search API 会使用服务账户所属的文件夹。

切勿提交凭据，也不要在共享的 MCP 配置中填写明文凭据。更改环境后，请重启客户端。

客户端配置

选择一种身份验证方式：API 密钥或 IAM 令牌。切勿同时传入两者。在 Codex 和 Claude Code 示例中，这些变量已在客户端进程环境中导出。

Codex CLI / IDE

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.yandex-wordstat]
command = "npx"
args = ["-y", "wordstat-mcp-server@latest"]
env_vars = ["YANDEX_WORDSTAT_API_KEY"]

使用 Yandex 账户或联合账户 IAM 令牌时，请使用：

[mcp_servers.yandex-wordstat]
command = "npx"
args = ["-y", "wordstat-mcp-server@latest"]
env_vars = ["YANDEX_WORDSTAT_IAM_TOKEN", "YANDEX_WORDSTAT_FOLDER_ID"]

运行 codex mcp list 以验证连接。Codex CLI 和 IDE 共用此配置。

Claude Code

claude mcp add-json --scope user yandex-wordstat \
  '{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_API_KEY":"${YANDEX_WORDSTAT_API_KEY}"}}'
claude mcp list

Yandex 账户或联合账户 IAM 令牌版本：

claude mcp add-json --scope user yandex-wordstat \
  '{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_IAM_TOKEN":"${YANDEX_WORDSTAT_IAM_TOKEN}","YANDEX_WORDSTAT_FOLDER_ID":"${YANDEX_WORDSTAT_FOLDER_ID}"}}'
claude mcp list

Hermes Agent

将服务添加到用户级 ~/.hermes/config.yaml：

mcp_servers:
  yandex_wordstat:
    command: "npx"
    args: ["-y", "wordstat-mcp-server@latest"]
    env:
      YANDEX_WORDSTAT_API_KEY: "your-api-key"

Yandex 账户或联合账户 IAM 令牌版本：

mcp_servers:
  yandex_wordstat:
    command: "npx"
    args: ["-y", "wordstat-mcp-server@latest"]
    env:
      YANDEX_WORDSTAT_IAM_TOKEN: "your-iam-token"
      YANDEX_WORDSTAT_FOLDER_ID: "your-folder-id"

Hermes 仅会将明确列出的变量传递给 stdio 服务。请勿提交包含凭据的用户配置。

运行 hermes mcp test yandex_wordstat，然后重启 Hermes 或使用 /reload-mcp。Hermes 会为工具注册 mcp_yandex_wordstat_ 前缀。默认情况下会禁用并行工具调用，以帮助控制 API 用量。

工具

工具	用途	主要输入
wordstat_top_requests	过去 30 天的热门请求和关联请求	短语、数量、地区、设备
wordstat_dynamics	按日、周或月统计的需求动态	短语、周期、日期范围、地区、设备
wordstat_regions	过去 30 天按地区统计的数量、占比和关联指数	短语、地区类型、分页、名称解析
wordstat_regions_tree	支持的地区层级	深度和可选的根地区
wordstat_find_regions	本地地区名称到 ID 的查询	查询内容、可选的父级、可选的子级

设备类型包括 all、desktop、phone 和 tablet；all 必须单独使用。每个请求最多可包含 100 个地区 ID。wordstat_find_regions 会搜索缓存的地区树。缓存未命中时，若设置了 resolve_names: true，wordstat_regions 可能会额外调用一次免费的地区树 API。每个额外的 wordstat_regions 页面都会重复调用收费的地区分布 API，因此需要完整结果集时，请使用最大的 limit。

动态数据日期与运算符

日期格式为 YYYY-MM-DD。如果两个边界都未指定且 auto_dates: true，服务端会根据粒度请求最近 60 个完整日、52 个完整周或 12 个完整月。如果只缺少一个边界，服务端会计算该边界；自动添加的 to_date 始终以最近一个完整周期结束。显式指定的边界不会调整。当 auto_dates: false 时，只要求提供 from_date；to_date 可以省略。

每日范围不能超过 60 天。对于每周和每月的详细数据，Wordstat 规定的范围为 3 周或 3 个月至 5 年，最早可用历史数据始于 2018 年 1 月。每周从周一到周日，每月从当月第一天到最后一个日历日。

每日动态数据支持 -、!、+、引号、[]、() 和 |；每周和每月动态数据仅支持 +。每周和每月详细数据中明确不支持的运算符会在产生费用的 API 调用前被拒绝。

结果元数据

每个成功的结果都包含：

• api_calls：逻辑上的 Wordstat 调用次数，包括免费的区域树方法；
• http_attempts：所有 HTTP 尝试次数，包括重试；
• billable_calls_estimate：费用估算值；实际费用以 Yandex 计费结果为准；
• local_hourly_budget_remaining：进程本地每小时剩余额度，或 null；
• content_truncated：是否因内容过长而缩短了 MCP 文本内容。

计数以字符串形式表示，以保留 64 位整数精度。

Agent 提示词示例

语义扩展

Build a keyword set for "online English courses". Show 100 popular requests and related
requests for the last month. Group them by intent: learning, price, format, level, and brand.
Highlight the five most popular phrases in every group. Keep popular and related requests separate.

区域需求对比

Compare demand for "flower delivery" in Moscow and Saint Petersburg over the last 12 complete
months. Find the correct regions yourself. Show monthly dynamics for each city, highlight the
highest and lowest months, and explain differences in seasonality. Do not invent missing data.

区域兴趣度

Show where interest in "ski resort" is strongest. Create two lists: the top 15 regions by
affinity index and the top 15 by request count. Include count, share, and affinity index for
each region. Briefly explain why the lists differ. Load additional pages only when necessary.

季节性及与去年对比

Analyze demand for "air conditioner" in Russia over the last 24 complete calendar months,
excluding the current month. Use Russia region ID 225 and explicitly set the start and end dates.
Compare every month with the same month one year earlier. Show the change in requests and percent,
and identify the start and peak of the season. If data is missing, list the missing months and
compare only complete pairs. If the earlier value is zero, do not calculate a percentage change.

设备差异

Compare demand for "grocery delivery" on desktop, phone, and tablet over the last 60 complete
days. For each device, show the total request count, daily average, and its share among the three
device types. Compare only dates present in every result. Do not call request counts unique users.

Wordstat 运算符影响

Show how quotation marks affect statistics for "apartment renovation". Over the last 60 complete
days, compare the plain query `apartment renovation` with `"apartment renovation"`. Show the total
count for each, the difference between them, and explain in simple terms what quotes restrict.

控制研究成本

Research "mortgage": popular and related requests, monthly dynamics, and regional interest.
First tell me how many billable Wordstat calls this will require and wait for confirmation.
After the research, show the actual number of calls and note any retry attempts separately.

配置

变量	默认值	范围 / 取值
YANDEX_WORDSTAT_API_KEY	—	恰好一个凭证
YANDEX_WORDSTAT_IAM_TOKEN	—	恰好一个凭证
YANDEX_WORDSTAT_FOLDER_ID	—	最多 50 个字符；参见上文
YANDEX_WORDSTAT_TIMEOUT_MS	30000	1–300000
YANDEX_WORDSTAT_MAX_RETRIES	2	0–10
YANDEX_WORDSTAT_MAX_RPS	8	1–10000
YANDEX_WORDSTAT_MAX_RPH	100	0–1000000；0 表示禁用
YANDEX_WORDSTAT_MAX_CONCURRENCY	4	1–100
YANDEX_WORDSTAT_REGIONS_CACHE_TTL_MS	86400000	0–2592000000
YANDEX_WORDSTAT_LOG_LEVEL	error	silent、error、warn、info、debug

进程本地限制可防止意外支出，但不会在多个进程之间协调，也不能替代 Yandex Cloud 配额。重试会增加 http_attempts，而一次逻辑调用只消耗一单位的本地每小时额度。

故障排查

工具错误会返回 code、安全的 message、retryable，以及（如果可用）http_status、 retry_after_seconds 和 http_attempts。

症状	检查
CONFIGURATION_ERROR	是否恰好提供了一个凭证，且数值设置在有效范围内
HTTP 400 / VALIDATION_ERROR	短语、日期、周期、运算符、地区 ID 和文件夹 ID
HTTP 401 / AUTHENTICATION_ERROR	凭证是否有效，以及客户端是否继承了环境变量
HTTP 403 / AUTHORIZATION_ERROR	是否已在正确的文件夹上授予 search-api.webSearch.user 权限
HTTP 429 / RATE_LIMITED	降低 RPS/并发数，或等待 retry_after_seconds
TIMEOUT / NETWORK_ERROR	连通性、API 可访问性和 YANDEX_WORDSTAT_TIMEOUT_MS
动态数据为空	请求的是否为完整的受支持周期，且地区筛选条件是否有效

日志仅写入 stderr。诊断时可暂时将 YANDEX_WORDSTAT_LOG_LEVEL=debug。绝不会记录凭证和 Authorization 标头。

开发

npm install
npm run build
YANDEX_WORDSTAT_API_KEY='...' node dist/cli.js

离线检查：

npm run check
npm test
npm run smoke:package

npm run contract:probe 和 npm run smoke:live:mcp 会连接真实 API，可能消耗配额，且只能在已配置凭证后显式运行。

安全

此服务不会修改数据，只会调用 Wordstat API。查询短语和地区标签仍来自外部来源：Agent 必须将其视为不可信内容，而非指令。如需私下报告漏洞，请参阅 SECURITY.md。

许可证

MIT