yandex-mcp

Сервер MCP, который предоставляет API Yandex Webmaster, Yandex Direct и Yandex Metrika как инструменты для ИИ-ассистентов (Claude Desktop, Claude Code, Cursor и др.).

Он позволяет ассистенту работать с вашими данными SEO, рекламы и аналитики Yandex на естественном языке — просматривать поисковые запросы, управлять индексацией и картами сайта, запрашивать переобход, запускать диагностику, управлять кампаниями Direct с защитой записи и получать статистику по трафику, конверсиям и рекламе — без входа в веб-интерфейс Yandex.

• 125 tool всего: 52 для Webmaster, 46 для Direct, 25 для Metrika, 2 для управления проектами.

• 6 MCP-проектов — элементы приложений готовые сценарии (аудит кампании, еженедельный отчёт, запуск кампании, масштабирование бюджета, SEO-аудит, проверка усвоения) на playbook по autostrategies, который также публикуется как MCP resource yandex://playbook.

• Один сервер, много-проектовая: several Yandex-аккаунтов/токенов в одном stdio-процессе.

• TypeScript / Node ≥ 22, построенный на @modelcontextprotocol/sdk и zod.

Как это работает

src/index.ts поднимает один McpServer и регистрирует все группы инструментов из src/webmaster/ и src/direct/. Все запросы проходят через src/client.ts — HTTP-клиента для каждого проекта, который:

• добавляет заголовок Authorization: OAuth <token> (Bearer для Direct),

• направляет запросы Webmaster на api.webmaster.yandex.net, а Direct — на api.direct.yandex.com/json/v5 (или в Direct Sandbox, если включён direct.sandbox),

• определяет и кэширует user_id Webmaster и подставляет host_id в пути,

• повторяет запросы при сетевых ошибках / 429 с экспоненциальной задержкой и обрабатывает 204 No Content,

• распаковывает внутренние ошибки Direct в теле ответа {"error": {...}} и следит за заголовком квоты Units.

Related MCP server: Yandex Wordstat MCP

Предварительные требования

• Node.js ≥ 22.

• OAuth-токен Yandex с доступом к API Webmaster и/или Metrika.

Получение OAuth-токена

1. Заре.hasNextRegisterthe app in the Yandex OAuth consolе and выдайте ему прова Webmaster (webmaster:hostinfo, webmaster:verifion) and/or Metrika (metrika:read / metrika:write) scopes.

2. Get the token for your account via OAuth flow.

Notes:

• Direct требует собственнной области приложения и одобренной заявки (request), поданной из аккаунта Direct после регистрации приложения — существующие токенs Webmaster/Metrika не подойдут для Direct, пока не перевыпустить. Until access approved, use the Direct Sandbox (direct.sandbox: true in the project config).

• OAuth-токены Webmaster expire after 6 месяцs and must be reissued.

Настройка

npm install
cp .env.example .env      # then put your token in .env
npm run build

.env:

YANDEX_OAUTH_TOKEN=your_oauth_token_here

Запуск

npm start          # runs dist/index.js (requires build)
npm run dev        # tsx watch mode against src/index.ts

Сервер по MCP через stdio, поэтому его обычно запускает MCP-клиент, а не вручную.

Конфигурация нескольких проектов

Сервер может обслуживать несколько проектов, у каждого из которых свой логин/токен Yandex. Скопируйте projects.example.json в projects.json (в .gitignore) и заполните его, либо укажите YANDEX_PROJECTS_CONFIG другой путь. Если файла конфигурации нет, но задан YANDEX_OAUTH_TOKEN, используется один проект default.

Переключайте активный проект через yandex_set_active_project, смотрите список через yandex_projects_list или передавайте project в любой инструмент Direct или Metrika. Инструменты Metrika также учитывают default_counter проекта.

Настройки Direct для отдельных проектов: sandbox (маршрутизация в Direct Sandbox), allow_login (агенцкие аккаунты) и limits — максимально допустимое изменение бюджета/ставки в процентах, ограничение применяют инструменты записи.

Подключение к MCP-клиенту

Токен считывается из переменной окружения YANDEX_OAUTH_TOKEN.

Claude Desktop / Cursor

Добавьте в конфигурацию MCP-серверов (claude_desktop_config.json или эквивалент):

{
  "mcpServers": {
    "yandex": {
      "command": "node",
      "args": ["/absolute/path/to/yandex/dist/index.js"],
      "env": {
        "YANDEX_OAUTH_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Claude Code

claude mcp add yandex --env YANDEX_OAUTH_TOKEN=your_token -- node /absolute/path/to/yandex/dist/index.js

Инструменты

Webmaster (52)

Все имена инструментов имеют префикс yandex_webmaster_.

Direct (43)

Все имена инструментов имеют префикс yandex_direct_. Инструменты записивают предварительно diff до изменения, not iff confirm: true, и следат проектных лимитах бюджета/ставки (обход — force: true). Set direct.sandbox: true in the project to route вызовы into Direct Sandbox. Результаты записиваются с сводкой по каждому эlementа — Direct сообщает о чатчных failures в hello успешного HTTP-ответа, therefore check the partial_failure.

Управление проектами (2)

yandex_projects_list, yandex_set_active_project — the same config for the Configuraция тних проектов.

Metrika (22)

Все имена инструментов имеют префикс yandex_metrika_. Стат-инструменты принимают direct_client_logins для рекламных отчётов (метрики ym:ad: — расходы Direct в объединении с поведением на сайте) и extra_params для любого другого параметра запроса.

Инструменты отчётности повторяют Metrika Reporting API. Метрики и измерения используют пространства имён ym:s: (визиты) / ym:pv: (просмотры страниц) — например, metrics: "ym:s:visits,ym:s:users,ym:s:bounceRate", dimensions: "ym:s:date,ym:s:lastTrafficSource". Даты принимают YYYY-MM-DD или относительные ключевые слова (today, yesterday, 7daysAgo). Инструменты, привязанные к счётчику, по умолчанию используют default_counter проекта, если counter_id/ids не указаны.

Структура проекта

src/
  index.ts            # entry point: boots the MCP server, registers all tools
  client.ts           # per-project HTTP client (auth schemes, base URLs, retries, Direct transport)
  projects.ts         # project registry: per-project tokens, Direct config, limits
  server-tools.ts     # project management tools (list / set active)
  webmaster/          # 14 modules, 51 Webmaster tools
  metrika/            # management + Reporting API — 10 Metrika tools
  direct/             # read, guarded write, reports — 14 Direct tools

Скрипты

Лицензия

MIT © Minas Sarkisyan