yandex-metrika-mcp-server

Yandex Metrika MCP Server

Yandex Metrika API 用の MCP サーバーです。108 個すべてのメソッドに対応しています。デフォルトで公開されるのは、よく使われる 10 個です。残りは環境変数ひとつで有効にできます。

mcp-name: io.github.artgas1/yandex-metrika-mcp-server

English

npx -y yandex-metrika-mcp-server

atomkraft/yandex-metrika-mcp のフォークです（アップストリーム — Vadim Bezymianyi、MIT）。 バージョン 2.0.0 以降、ツールは手作業で作成するのではなく、公式ドキュメントを基にまとめた仕様から生成されます。

対応範囲

API	メソッド数	core プロファイルに含まれる数	ツールの例
Management	95（21 リソース）	4	metrika_counter_list、metrika_goal_create、metrika_segment_update
Logs	7	—	metrika_logs_create、metrika_logs_get、metrika_logs_download
Stat	6	6	metrika_stat_data、metrika_stat_bytime、metrika_stat_pivot

ツール名は metrika_<resource>_<action> です。リソース名は、名前を変更せずに API 自体の URL から取得します。 そのため、metrika_goal_list は GET /management/v1/counter/{id}/goals と、その専用ドキュメントページに一意に対応します。

契約

観測された 2 つの問題、つまり要求とは異なる内容を返すこと、フィルターを暗黙に追加することを受け、サーバーを書き直しました。これを踏まえた 5 つのルールには、それぞれテストがあります。

1. 暗黙の置き換えはしません。 要求された内容をそのまま API に送信します。サーバーがディメンション、期間、フィルターを勝手に補うことはありません。
2. サーバーが独自に追加した内容は、すべて応答に表示されます。 応答は {"_meta": {...}, "data": {...}} の形式で返されます。_meta.applied_by_server には追加した内容が、_meta.notes には呼び出し元に代わって行った判断が記載されます。
3. エラーはエラーのまま返します。 API エラーは isError: true と Metrika の応答本文を含めて返されます。再試行はテキスト内の部分文字列ではなく、ステータス（429/500/502/503/504 とネットワークエラー）に基づいて行われます。429 の場合は Retry-After に従います（上限は 30 秒）。再試行回数は常に _meta.retries で確認できます。
4. 出力の切り捨ては明示されます。 _meta には rows_returned、rows_total、truncated が含まれます。Metrika はデフォルトで応答を切り詰めるため、これを黙って済ませることはできません。サーバーが長さの上限により応答を短縮した場合は、破棄された行数とともに _meta.truncated_by_server に別途記録されます。
5. シークレットは応答に含まれません。 metrika_measurement_delete には token パラメーターがあります。表示される _meta.request_url では、その値は REDACTED に置き換えられます。OAuth トークン自体はヘッダーでのみ送信され、応答に含まれることはありません。

Фильтр роботов

В отчётах Stat API по умолчанию применяется собственный флаг робота Метрики, и только он:

ym:s:isRobot=='no'

Он объявлен: виден в схеме инструмента, отключается параметром human_traffic_only: false и всегда перечислен в _meta.applied_by_server. Если в запросе есть метрики ym:ad: или ym:ev:, фильтр не применяется (Метрика отвечает на такое сочетание 400) — и это попадает в _meta.notes, а не остаётся молчаливым исключением.

Своё условие задаётся переменной METRIKA_TRAFFIC_FILTER — целиком, включая isRobot, если он нужен:

METRIKA_TRAFFIC_FILTER="ym:s:isRobot=='no' AND ym:s:browserName!='HeadlessChrome'"

Это образец формы, а не рекомендация. Какой рез верен — зависит от того, какие боты ходят именно к вам: отсечка по стране, по заголовку браузера или по подсети осмысленна только на своих данных. Копировать чужой список бессмысленно и опасно: он вырежет живой трафик.

Заданное своё условие сервер называет в stderr при старте — оно меняет числа в каждом отчёте, и молчать об этом нельзя.

Сравнение периодов: ответ, который выглядит валидным

У metrika_stat_comparison и metrika_stat_comparison_drilldown даты периодов необязательны, и Метрика на их отсутствие не ругается. Она подставляет собственное окно (последняя неделя) в оба набора и возвращает сравнение периода с самим собой:

metrika_stat_comparison(ids, metrics)  →  totals a == b
                                          query  date1_a == date1_b

Отказывать сервер не будет — запрос ушёл ровно тем, каким его собрали. Но такой ответ приходит с пометкой в _meta.notes: и когда даты не заданы, и когда периоды совпали явно.

Как устроена спека

Публичного openapi.json у Метрики нет, но каждая страница метода сгенерирована из OpenAPI движком Diplodoc и отдаётся как text/markdown. Семантика (тип, required, комбинатор, ассертация) лежит в CSS-классах вида {.json-schema-property}, поэтому спека собирается построчным сканером по классам, а не markdown-парсером.

npm run spec:fetch   # скачать llms.txt и 108 страниц в .cache/docs/
npm run spec:build   # разобрать их в spec/metrika-api.json
npm test             # тесты спеки и схем инструментов
npm run smoke        # живые вызовы к API (нужен YANDEX_API_KEY)

spec/metrika-api.json коммитится — это состав API на момент сборки. Тест на дрейф сверяет его с llms.txt: Яндекс добавил или удалил метод — тест краснеет.

Разбор привязан к версии генератора (Diplodoc Platform v5.57.3): вся семантика висит на его классах, поэтому расхождение версии останавливает сборку спеки, а не молча портит её.

Запуск

По умолчанию объявляются десять инструментов из 108 — те, которыми считают. Управление счётчиками и целями, доступы и Logs API включаются переменной METRIKA_PROFILE; подробности ниже, в разделе «Почему по умолчанию не всё».

Спросить у самого сервера тоже можно: инструмент metrika_catalog_list перечисляет, что объявлено, что скрыто и как это включить.

npm install
npm run build
YANDEX_API_KEY=<OAuth-токен с scope direct:api / metrika> npm start

Токен — OAuth Яндекса, тот же, что используется для Директа и Вебмастера.

По умолчанию сервер сохраняет stdio-режим. Для одного локального процесса, к которому подключаются несколько MCP-клиентов, включите stateless Streamable HTTP:

YANDEX_API_KEY=<OAuth-токен> \
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=13404 \
npm start

Endpoint — http://127.0.0.1:13404/mcp. При loopback-привязке сервер также проверяет Host, чтобы локальный endpoint нельзя было вызвать через DNS rebinding.

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

{
  "mcpServers": {
    "yandex-metrika-mcp": {
      "command": "npx",
      "args": ["-y", "yandex-metrika-mcp-server@3"],
      "env": { "YANDEX_API_KEY": "..." }
    }
  }
}

Из локальной сборки — то же самое, но "command": "node" и путь до build/index.js.

Мажор в строке запуска закреплён намеренно: смена мажорной версии меняет набор инструментов по умолчанию, и получать это молча при старте агента не нужно.

Переменные окружения

Переменная	По умолчанию	Что делает
YANDEX_API_KEY	—	OAuth-токен. Без него сервер не стартует.
MCP_TRANSPORT	stdio	Транспорт: stdio или stateless Streamable http.
MCP_HOST	127.0.0.1	Адрес HTTP listener. Используется только при MCP_TRANSPORT=http.
MCP_PORT	3000	Порт HTTP listener, целое число от 1 до 65535.
METRIKA_PROFILE	core	Какая часть каталога объявляется: core (10 инструментов), read (все 51 читающих), all (все 108). Неизвестное значение роняет старт.
METRIKA_ALLOW_WRITES	не задана	1 разрешает и объявляет 57 инструментов, меняющих данные. Пока не задана — их нет в tools/list вовсе.
METRIKA_TOOLS	пусто	Своя выборка через запятую: раздел (stat, logs, management), префикс имени (metrika_goal) или точное имя. Задана — побеждает профиль.
METRIKA_TRAFFIC_FILTER	ym:s:isRobot=='no'	Условие сегментации, добавляемое к отчётам Stat. Задаётся целиком.
METRIKA_MAX_OUTPUT_CHARS	120000	Потолок длины ответа одного вызова. Выгрузка Logs API в него обычно не помещается — сутки визитов это сотни тысяч символов; урезание объявляется в _meta.truncated_by_server.
METRIKA_API_BASE	пусто	Подмена адреса API (прокси, заглушка в тестах). Факт подмены печатается в stderr.

Как узнать, что скрыто, не открывая README

Инструмент metrika_catalog_list объявлен в любом профиле и отвечает из спеки, лежащей в пакете, — ни токена, ни сети ему не нужно:

{
  "profile": "METRIKA_PROFILE=core",
  "api_methods_total": 108,
  "api_methods_declared": 10,
  "api_methods_hidden": 98,
  "writes_enabled": false,
  "declared_tools": { "Stat API — отчёты": ["metrika_stat_data", "…"] },
  "hidden_tools": { "Management API — …": ["metrika_goal_create", "…"] },
  "how_to_widen": ["METRIKA_PROFILE=read — …", "METRIKA_PROFILE=all вместе с METRIKA_ALLOW_WRITES=1 — …"]
}

Он существует по простой причине: сервер, который что-то скрыл, обязан уметь сказать, что именно и как это включить. instructions видит модель, но не человек — в интерфейс клиента они не показываются; стартовую строку в stderr в обычной работе тоже никто не открывает. Без этого инструмента узнать про остальные 98 можно было только придя сюда.

Список инструментов в ответе строится из того же отбора, по которому они регистрируются, — разойтись с реальностью ему негде, и это проверено тестом.

Почему по умолчанию не всё

Описания объявленных инструментов лежат в контексте модели, когда клиент их загрузил. Это цена сервера, которую платят за сам факт подключения, а не за вызовы. Замер tools/list (09.09.2026):

Профиль	Инструментов	tools/list	токенов
core (по умолчанию)	10 + каталог	32 181 Б	14,8 тыс.
read	51 + каталог	68 074 Б	~31 тыс. — оценка
all + METRIKA_ALLOW_WRITES=1	108 + каталог	158 301 Б	~73 тыс. — оценка

Замер core — 14,5 тысячи до появления каталога и 14,8 после: сам инструмент стоит около 670 байт схемы, примерно 2% набора. Его ответ не входит в эту цену — он платится только при вызове.

Байты точные, их воспроизведёт любой: сериализуй ответ tools/list и посчитай длину. С токенами сложнее, и здесь стоит сказать прямо.

⚠️ Замер честный только у core — его дал /context клиента, который считает собственным токенизатором. Две другие строки пересчитаны из байтов по калибровке 2,17 байта на токен, снятой с той же строки core.

Ходовая эвристика «4 символа на токен» здесь врёт почти вдвое: она выведена на английском тексте, а описания у этого сервера русские, и кириллица в BPE токенизируется примерно вдвое хуже латиницы. Первая редакция этой таблицы была построена именно на ней и называла для core 7,9k вместо 14,5k. Если считаешь бюджет контекста для сервера с не-английскими описаниями — считай токенизатором, а не делением на четыре.

Состав core выведен из замера реального использования, а не из вкуса: шесть отчётов Stat плюс справочники, без которых отчёт не собрать (metrika_counter_list, metrika_counter_get, metrika_goal_list, metrika_segment_list). Порог веса стоит тестом — манифест не может подорожать молча. Порог в тесте стоит на байтах: они не зависят ни от токенизатора, ни от языка описаний.

Безопасность

• Запись выключена по умолчанию, и меняющие инструменты не объявляются вовсе. Среди методов четырнадцать DELETE и пять удаляющих POST (.../measurement/delete, .../expense/delete, .../logrequest/{id}/clean и т. д.). Цена ошибочного вызова — удалённый счётчик или цель без возможности восстановить историю. Модель не может позвать то, чего не видит в tools/list; как включить — сказано в instructions сервера.
• Аннотации проставлены на всех инструментах (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Клиент по ним отличает чтение от удаления: удаление под глаголом POST помечено разрушающим, PUT — тоже, потому что заменяет сущность целиком.
• Ответы Метрики — недоверенные данные. В отчётах лежат поисковые фразы, заголовки страниц, реферера и значения UTM, то есть строки, которые пишут посетители сайта. Любой может зайти на сайт по ссылке с текстом внутри и увидеть его в отчёте. У всех инструментов openWorldHint: true, а в _meta.notes отчётов и выгрузок едет напоминание, что это данные, а не инструкции.
• stdio остаётся транспортом по умолчанию. HTTP включается только явно через MCP_TRANSPORT=http; безопасный дефолт слушает 127.0.0.1 и проверяет Host.

プライバシーポリシー

サーバーは、あなたに関するデータを収集、保存したり、外部に送信したりしません。テレメトリーも分析も、作者のサーバーへのリクエストもありません。これらは存在せず、このパッケージ用にインフラストラクチャも構築されていません。

唯一のネットワーク上の送信先は https://api-metrika.yandex.net です。トークンは YANDEX_API_KEY からプロセスメモリに読み込まれ、どこにも書き込まれません。ファイルにも、stdout にも、レスポンス本文にも書き込まれません。レポートデータはディスクにキャッシュされず、プロセスの終了後に残りません。

リクエストしたデータは、メトリカの運営者であるヤンデックスによって処理されます。適用されるのはこのポリシーではなく、ヤンデックスのポリシーです。

全文は PRIVACY.md をご覧ください。

1 つのファイルでインストール（MCPB）

Claude Desktop や、MCP バンドルに対応したその他のクライアント向けに、.mcpb ファイルを用意しています。リリースから入手できます。ファイルを開き、インストール画面でトークンを入力すれば完了です。

バンドルは同じコードから同じタグでビルドされます（npm run mcpb）。マニフェストは package.json とプロファイルから生成され、手作業では作成されません。そのため、サーバーとの不整合が生じる余地はなく、テストで検証されています。

⚠️ バンドルでは書き込みを有効にできません。 誤った呼び出しをすると、履歴を復元できないままカウンターや目標が削除される可能性があります。インストール画面に、そのような切り替えスイッチを設けるわけにはいきません。書き込みが必要な場合は、npm からパッケージをインストールし、環境変数で明示的に有効にしてください。

MCP を使わない場合：スキルとコマンドライン

MCP が常にすべての人に適しているとは限りません。クライアントが MCP にまったく対応していない場合もあります。また、ツールの説明はコンテキストを常に占有します。サーバーが接続されている間は、呼び出しているかどうかにかかわらず、コンテキスト内に残ります。

このような場合、同じサーバーをコマンドで起動できます。

npx -y yandex-metrika-mcp-server catalog --search goal
npx -y yandex-metrika-mcp-server describe metrika_stat_data
npx -y yandex-metrika-mcp-server call metrika_stat_data \
  --ids <ID счётчика> --dimensions ym:s:trafficSource \
  --metrics ym:s:visits,ym:s:users --date1 7daysAgo --date2 today

その上にあるのがスキルです。エージェント向けの指示を含むフォルダーで、1 行のコマンドでインストールできます。

npx skills add artgas1/yandex-metrika-mcp        # в текущий проект
npx skills add artgas1/yandex-metrika-mcp -g     # глобально, во все проекты

スキルはクライアントにツールを追加せず、コンテキストも占有しません。メトリカの話題になったときだけ読み込まれます。中身は同じコマンド、108 個すべてのメソッドのリファレンス、ディメンションの辞書です。

対応状況。 インストーラーは .agents/skills/yandex-metrika/ に 1 つのインスタンスを配置し、それを各エージェントのフォルダーにシンボリックリンクします。2 つのエージェントで起動して確認済みです。

エージェント	検出方法	確認内容
Claude Code	.claude/skills/ → シンボリックリンク	/yandex-metrika がスキルの内容に基づいて応答する
Codex	.agents/skills/ を直接参照	SKILL.md のパスを示す。このために AGENTS.md に 1 行も追加する必要はなく、config.toml の設定も不要

インストーラーは同じユニバーサルディレクトリを通じて、ほかにも約 20 個のエージェント（Amp、Cline、Antigravity、Augment など）をサポートするとしています。これらについては確認していません。

これが別の実装ではない理由。 CLI は独自のリクエストを一切行いません。引数を解析して、MCP ツールと同じ executeMethod 関数を呼び出します。そのため、レポートでのロボットフィルター、切り詰めを通知するレスポンス上限、表示 URL からのシークレット除去、ステータスに基づく再試行といった保証も同じです。異なるものがないため、実装が食い違う余地もありません。

スキル内のメソッドリファレンスは、ヤンデックスのドキュメントを毎日反映して更新される spec/metrika-api.json から生成されます。テストでは、コミット済みのファイルと、現在生成されるはずのファイルを照合します。そのため、「スキルが API に追いついていない」状態は見逃されず、テスト失敗として検出されます。

コマンドには、MCP と異なる点が 2 つあります。

	MCP	コマンド
METRIKA_PROFILE	適用されます。デフォルトは core です	適用されません — 108 個すべてのメソッドを利用できます
METRIKA_ALLOW_WRITES	データを変更する場合に必要です	同様に必要です

プロファイルは、呼び出さないツールの説明によってコンテキストを消費しないために存在します。ターミナルでコマンドを使う場合、そのようなコストはありません。書き込みのゲートは別の問題です。削除された目標は復元できず、ここで制限を緩めるとサーバーを迂回する抜け穴になります。

チェック

Не макет — запустите сами

npm run demo

^{Всё на записи приходит из ответа сервера по JSON-RPC: строка добавленного фильтра — из _meta.applied_by_server, строки отчёта — из тела ответа. Ни токена, ни сети: запросы уводятся на локальную заглушку, поэтому прогон повторяется где угодно, включая CI. Переснять запись — npm run demo:record.}

npm test          # 87 тестов: спека, схемы, протокол MCP, поверхность, бандл, демо
npm run protocol  # только протокольные: stdio, tools/list, tools/call, отказы
npm run smoke     # живые вызовы к API (нужен YANDEX_API_KEY)

Протокольные тесты поднимают сервер как подпроцесс и говорят с ним по JSON-RPC — тем же способом, каким это делает клиент. Сеть при этом не нужна: METRIKA_API_BASE уводит запросы на заглушку. Проверяется в том числе то, чего не видно изнутри: что в stdout не попадает ничего, кроме JSON-RPC, что отказ API приезжает как isError, а не как успешный текст, и что запись действительно заблокирована.

Чего в проверках НЕТ

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

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

Что изменилось в 2.0.0

Удалены 26 инструментов-обёрток над пресетами Stat API (get_visits, sources_summary, get_page_performance и прочие). Они покрывали малую часть API, зашивали измерения и период в код и не давали задать произвольный запрос. Их заменяют metrika_stat_*, принимающие параметры Stat API как есть.

Появились методы, которых не было вовсе: список счётчиков, цели, сегменты, фильтры, разрешения, расходы, офлайн-конверсии и весь Logs API. Раньше идентификатор счётчика приходилось знать заранее — теперь его можно найти.

Что изменилось в 2.1.0

Сервер довели до состояния, в котором его не страшно оставить агенту.

• Аннотации на всех 108 инструментах. До этого клиент не отличал metrika_counter_list от metrika_counter_delete.
• Запись выключена по умолчанию (METRIKA_ALLOW_WRITES).
• Найден и починен дефект разбора документации. Ассертации размечены строкой, где значение стоит после закрывающей скобки класса, — распознаватель свойств заякорен на конец строки и такие строки не матчил вовсе. В итоге до спеки не доезжало ни одного примера, значения по умолчанию или границы, а часть их падала в описание соседнего поля. Сейчас в спеке 288 примеров, 69 значений по умолчанию и 155 ограничений; ограничения переносятся в схему инструмента, примеры и значения по умолчанию — в описания параметров.
• Найдена и починена потеря обязательности. Параметры вида «один из N типов» (goal у создания и правки цели, grant у выдачи доступа) собирались как z.unknown(), а он в zod необязателен, — обязательное поле уезжало клиенту как опциональное. Теперь это объединение реальных форм, и обязательность на месте.
• Ссылки на сущности разворачиваются на один уровень: у 23 параметров тела вместо свободного объекта видны настоящие поля.
• Послабления на входе там, где они безвредны. Число строкой, булево словом, список через запятую в строке запроса — принимаются; в теле запроса, где важен точный JSON, не принимаются.
• Потолок длины ответа с объявленным урезанием: выгрузка Logs API бывает в сотни мегабайт.
• Вычистка секретов из показанного request_url.
• Повтор на 429 с соблюдением Retry-After.
• SDK обновлён до 1.30 — на 1.17 висели три опубликованных уязвимости, две высокие; npm audit --audit-level=high теперь часть CI.
• Починена джоба дрейфа в CI. Она запускала тесты через | tee без pipefail, поэтому код возврата брался у tee и джоба оставалась зелёной при любом падении теста.