Яндекс Директ API v5

io.github.artgas1由 GitHub 帳號 artgas1 發布v1.1.1更新於 Oct 24, 2026

MCP server for Yandex Direct API v5: 113 methods from the machine-readable schema

已驗證STDIO僅桌面資料與分析商業與電商

概覽

AI 產生的概覽

針對 Yandex Direct API v5 的 MCP 伺服器與命令列工具,提供 113 個由結構描述產生的方法,讓助理讀取廣告帳戶資料,並在開啟後進行修改。

可以做什麼
  • 讀取廣告活動、廣告群組、廣告、關鍵字與指定目標設定
  • 讀取出價、出價調整與投放策略
  • 產生報表並取得字典與參考資料
  • 列出客戶與代理商帳戶,並提供目錄、欄位與結構描述查詢工具
  • 結合廣告活動清單與報表彙整完整帳戶清單
  • 開啟寫入後可新增、修改、暫停、封存或刪除物件
適用情境
適合需要檢視或管理 Yandex Direct 廣告帳戶的情境:廣告活動結構、指定目標、出價、報表與代理商客戶。也適合希望由伺服器處理 API 隱性陷阱(微單位金額、超長 ID、HTTP 200 卻含錯誤、報表延遲)而非直接面對原始回應的使用者。
執行需求
透過 npx 在本機執行(需要 Node.js)。需要具備 direct:api 權限範圍的 Yandex OAuth 權杖,放在 YANDEX_DIRECT_TOKEN 中,並需已核准的 Direct API 應用程式。選用設定:YANDEX_DIRECT_LOGIN(代理商帳戶)、DIRECT_PROFILE、DIRECT_TOOLS、DIRECT_API_VERSION、DIRECT_SANDBOX、DIRECT_ALLOW_WRITES、DIRECT_MAX_OUTPUT_CHARS。需要連線至 Yandex Direct API 的網路。
安裝前請注意
YANDEX_DIRECT_TOKEN 中的權杖可存取真實廣告帳戶及其預算。寫入預設關閉;設定 DIRECT_ALLOW_WRITES=1 會揭露 80 個修改方法與 16 個刪除方法,且沒有確認步驟,刪除無法復原。YANDEX_DIRECT_LOGIN 可能在同一權杖下無聲切換到另一個帳戶。測試時請用 DIRECT_SANDBOX=1 並搭配獨立權杖。API 呼叫會消耗點數並涉及真實金錢。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Яндекс Директ API v5,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

yandex-direct-mcp

MCP-сервер и командная строка к API Яндекс Директа v5. Покрыты все 113 методов, порождённые из машиночитаемой схемы; по умолчанию объявляются девять — те, которыми читают. Остальное включается одной переменной, изменение выключено.

mcp-name: io.github.artgas1/yandex-direct-api-mcp

[npm] [CI] [License: MIT]

English

Работает и как MCP-сервер для Claude Code, Cursor, Codex и других клиентов, и как обычная команда — если MCP не нужен.

Что это даёт — за пять секунд

[Запись прогона в терминале: вызов direct_campaigns_get и две колонки — слева тело ответа, разобранное обычным JSON.parse, справа то же самое после сервера. Бюджет 1000000000 против 1000, идентификатор объявления, испорченный разбором, против точного, обёртка Items против обычного списка и отказ с кодом HTTP 202, распознанный как отказ.]

Обе колонки настоящие: левая — тело ответа, разобранное обычным JSON.parse, то есть так, как его получил бы любой клиент; правая — то, что вернул сервер по JSON-RPC. Строка с идентификатором самодоказательна: слева он испорчен не потому, что так нарисовано, а потому что его действительно портит разбор. Ни токена, ни сети: запросы уводятся на локальную заглушку, поэтому прогон повторяется где угодно, включая CI. Повторить у себя — npm run demo, переснять — npm run demo:record (нужен vhs).

bash
npx -y yandex-direct-api-mcp

Покрытие

что покрытослужбметодовиз них в coreпримеры инструментов
Кампании и объявления9373direct_adgroups_get, direct_ads_get
Таргетинг9451direct_keywords_get
Ставки и стратегии4152direct_bidmodifiers_get, direct_keywordbids_get
Отчёты и справочники692direct_dictionaries_get, direct_reports_get
Клиенты и агентства271direct_clients_get
всего301139плюс четыре служебных: direct_catalog, direct_fields, direct_schema, direct_inventory

Таблица считается из спеки (npm run coverage), а не пишется руками: числа в прозе расходятся со схемой молча, и неправда выглядит ровно как правда.

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

Нужен OAuth-токен Яндекса со scope direct:api — https://oauth.yandex.ru/ (приложению требуется одобренная заявка на доступ к API Директа).

MCP:

json
{  "mcpServers": {    "yandex-direct": {      "command": "npx",      "args": ["-y", "yandex-direct-api-mcp"],      "env": { "YANDEX_DIRECT_TOKEN": "ваш-токен" }    }  }}

Командная строка:

bash
export YANDEX_DIRECT_TOKEN="ваш-токен"
yandex-direct-mcp catalog --service campaignsyandex-direct-mcp describe campaigns.getyandex-direct-mcp call campaigns.get --FieldNames Id --FieldNames Name

Что этот сервер делает за вас

Не удобства. Каждый пункт — место, где прямой запрос к Директу ошибается молча: ответ выглядит нормальным, ошибки нет, а число или вывод неверны. Всё перечисленное снято прогоном живого API, а не прочитано в документации.

Суммы приходят умноженными на миллион — всегда

DailyBudget.Amount = 1000000000     ← это 1000 единиц валюты счётаCost               = 1234500000     ← это 1234,50 единицы валюты счёта

Ошибка ровно в миллион раз, и она не выглядит ошибкой: число правдоподобное, его можно сложить, поделить и построить по нему график. Заголовок returnMoneyInMicros, который выключает микро-единицы в отчётах, на обычные службы не действует — проверено на campaigns, значение не изменилось.

Сервер приводит суммы к валюте счёта и перечисляет в ответе, какие именно поля пересчитал:

json
"_мета": { "суммы_переведены_из_микроединиц": ["Amount", "Refund", "Spend"] }

Идентификаторы объявлений не помещаются в число JavaScript

Типичный Id объявления: 1234567890123456789 — девятнадцать цифр. JSON.parse держит пятнадцать и превращает его в 1234567890123456800.

И это не единичный курьёз: девятнадцатизначные идентификаторы встретились в каждом проверенном кабинете, а не в одном экземпляре. Схема Яндекса объявляет 358 полей типом xsd:long — то есть диапазон до 19 цифр нормален по контракту.

Опасен не сдвиг, а то, как он выходит наружу: испорченный идентификатор Директ принимает и отвечает HTTP 200 с телом {"result":{}}. То есть отказа нет — есть сообщение «такого объявления нет». Пустота как доказательство отсутствия.

Сервер разбирает тело так, что длинные целые остаются точными. Отдельно проверено, что API принимает идентификатор строкой, поэтому точность держится на всём пути — и на чтении, и на записи.

Успех определяется телом, а не кодом ответа

что спросиликодчто в теле
неверный FieldNames200error_code: 8000
неизвестный метод202error_code: 55
ошибка в отчёте400error_code: "8000" — строкой, не числом
отчёт поставлен в очередь201пусто, retryIn: 1
отчёт считается202пусто, retryIn: 10

Один и тот же код 202 означает отказ у campaigns и «ещё считается» у reports. Проверка res.ok пропускает первые три строки таблицы: отказ уходит модели как удачный ответ.

Отчёт приходит не сразу

201 → 202 → 200. Замер: до готовности потребовалось три запроса. Повтор идёт с тем же ReportName — имя и есть ключ поставленной задачи. Сервер ждёт сам.

Версия пути меняет данные

Один и тот же запрос:

/json/v5/campaigns    → N кампаний, у всех Type = TEXT_CAMPAIGN/json/v501/campaigns  → те же N,     у всех Type = UNIFIED_CAMPAIGN

Это разные представления с разными наборами глубоких полей, и несовпадение отнимает их без всякого признака:

путьнабор полейглубокие поля
v5TextCampaignFieldNamesприходят
v5UnifiedCampaignFieldNamesпусто, ошибки нет
v501TextCampaignFieldNamesпусто, ошибки нет
v501UnifiedCampaignFieldNamesприходят

Стратегия, настройки, счётчики просто отсутствуют — читается как «у кампании ничего не настроено». Умолчание v501 (документация называет адресом только его), переключается DIRECT_API_VERSION=v5, выбранная версия печатается в каждом ответе, а несовпадающий набор полей вызывает предупреждение.

Список кампаний неполон

Кампании Мастера кампаний не отдаются методом campaigns.get вовсе — ни списком, ни по явному Ids; ответ пустой и без ошибки. Ни v5, ни v501 этого не меняют.

Поэтому состав кабинета собирает отдельный инструмент direct_inventory: он склеивает список кампаний и отчёт и помечает каждую строку источником. Предупреждения в описании тут мало — оно требует, чтобы читатель помнил про него в момент вывода, а вывод делается по данным, которые выглядят нормально.

Прогон на живом кабинете: объединение оказалось на кампанию длиннее списка, и эта строка была видна только отчёту. Невидимая для campaigns.get кампания при этом откручивается и может нести основную долю показов — по списку кампаний этого не заметить.

ВНИМАНИЕ: 1 кампаний откручивались, но методом campaigns.get НЕ отдаются          (10000017). Управлять ими через API нельзя — только в интерфейсе.

Предупреждение — это применено, а не отклонено

В ответе на add/update каждому входному элементу отвечает выходной. Различать надо по Errors; Warnings означает «применено с замечанием». Счёт по наличию любого содержимого даёт «отклонено всё» там, где применилось всё. Сервер приводит итог отдельной строкой:

UpdateResults: применено 2, отклонено 1, с предупреждениями 1

Форму списка задаёт тип, а не направление

RegionIds            (maxOccurs=unbounded) → [225, 977]RestrictedRegionIds  (тип ArrayOfLong)     → {"Items": [225]}

Обе формы одинаковы и на чтении, и на записи. Сервер снимает и ставит обёртку по графу типов, а не по виду значения, поэтому круг «прочитал → поправил → записал» не рвётся. Вам обе формы видны как обычные массивы.

Кабинет называется в каждом ответе

Client-Login переключает кабинет по-настоящему, и ошибиться в нём можно молча. Несуществующий логин отбивается кодом 8800 — это видно сразу. А существующий, но не тот, отдаёт полные и правильные данные, просто из другого кабинета: по виду ответа это неотличимо.

Поэтому сервер спрашивает у API, кто отвечает, и пишет ответ в каждый конверт:

json
"_мета": { "кабинет": "example-login (ClientId 1234567)", "версия_api": "v501" }

Спрашивается один раз за запуск и кешируется — clients.get стоит 10 баллов.

Поверхность

Описания всех объявленных инструментов лежат в контексте модели на каждом ходу, вызываете вы их или нет. Поэтому по умолчанию объявляется не всё, что умеет API, а то, чем пользуются.

[Список всех 113 методов API Директа: девять оставлены и выделены, 104 вычеркнуты. Манифест по умолчанию — 27 028 байт против 143 706 у полного каталога.]

Замер tools/list на собранном сервере (npm run surface):

профильинструментовбайт≈ токенов
core (умолчание)1327 02812 455
read3761 15828 183
all + DIRECT_ALLOW_WRITES=1117143 70666 224

Умолчание в 5,3 раза легче полного набора. Главный рычаг — вложенные типы не разворачиваются в схему: транзитивно campaigns.add это 1083 поля и 54 КБ на один инструмент. Вместо разворачивания состав типа назван словами в описании, а точная схема выдаётся инструментом direct_schema по запросу.

Чего не видно — расскажет сам сервер: инструмент direct_catalog перечисляет все 113 методов и говорит, какие скрыты и как их включить.

Изменение выключено по умолчанию

Из 113 методов 80 меняют данные, 16 удаляют. У Директа нет подтверждающего шага: suspend останавливает показы в момент вызова, archive убирает кампанию из работы, delete необратим, а на другом конце — деньги.

Меняющие инструменты не объявляются вовсе, пока не задан DIRECT_ALLOW_WRITES=1. Объявлять их и отказывать на вызове — худший вариант: контекст за них платится полностью, а позвать всё равно нельзя.

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

Есть песочница: DIRECT_SANDBOX=1 (нужны отдельная регистрация и отдельный токен). Факт включения печатается при старте и в каждом ответе.

Настройки

переменнаяпо умолчаниючто делает
YANDEX_DIRECT_TOKEN—OAuth-токен, scope direct:api. Обязательна
YANDEX_DIRECT_LOGIN—логин кабинета (не почта). Переключает кабинет по-настоящему: под одним токеном отдаёт другой аккаунт со своей квотой. Фактический кабинет сервер называет в каждом ответе
DIRECT_PROFILEcorecore, read, all
DIRECT_TOOLS—явный список служб или инструментов, побеждает профиль
DIRECT_ALLOW_WRITESвыкл.объявить меняющие данные инструменты
DIRECT_API_VERSIONv501v501 или v5 — меняет представление кампаний
DIRECT_SANDBOXвыкл.песочница вместо боевого кабинета
DIRECT_MAX_OUTPUT_CHARS60000потолок ответа; усечение называется вслух

Откуда берутся инструменты

Ни один метод не описан руками.

источникчто даётпочему нужен
WSDL 29 служб + 3 общие XSDсостав, типы, обязательность, массивность, перечисленияединственный полный: в индексе документации нет vcards, smartadtargets, dynamictextadtargets, dynamicfeedadtargets
страницы документациичеловекочитаемые описанияв WSDL нет ни одного xs:documentation
описано явнослужба reportsWSDL для неё Директ не отдаёт (404)

Итог: 30 служб, 113 методов, 609 типов, 240 перечислений.

bash
npm run spec:fetch    # скачать WSDL и документацию в .cache/npm run spec:build    # собрать spec/direct-api.json

⚠️ Перечисления из схемы отстают от живого API и поэтому не становятся жёстким фильтром, а идут подсказкой в описание. Сверка с живым API: campaigns принимает CreateTime, keywords — AutotargetingBrief, AutotargetingBriefSuggests, AutotargetingMode, которых в схеме нет. Фильтр по отстающему списку запретил бы то, что API умеет, и отказ выглядел бы как отсутствие возможности. Право решать остаётся за API.

Проверки

bash
npm test         # 70 тестов, включая отрицательные контролиnpm run surface  # замер поверхности по профилямnpm run coverage # таблица покрытия для READMEnpm run graphic  # пересобрать графику поверхности (SVG и GIF)npm run smoke    # прогон собранного сервера против живого API (нужен токен)

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

Скилл — работа без MCP

Для агентов, которым MCP не нужен или недоступен:

bash
npx skills add artgas1/yandex-direct-mcp

Ставит один канонический экземпляр в .agents/skills/yandex-direct/ и связывает его с каталогами агентов. Скилл — тонкая надстройка над той же командой: своей логики у него нет, поэтому расходиться с сервером ему нечем.

Если выбираете между серверами

Серверов к Директу написано много. Полезные вопросы к любому из них — те же, что перечислены выше: приводит ли суммы из микро-единиц; переживают ли девятнадцатизначные идентификаторы разбор; считается ли HTTP 200 с телом error успехом; ждёт ли он отчёт после 201; отличает ли Warnings от Errors; что делает при опечатке в имени профиля. Ответы стоят одного вызова.

Лицензия

MIT.

來源:README.md,提交 086ec45

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.1.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分