{
  "markdown": "<!-- mcp-name: io.github.dontsovcmc/yandex-direct -->\n\n# mcp-server-yandex-direct\n\n[![Version](https://img.shields.io/badge/version-0.3.0-blue)](https://github.com/dontsovcmc/mcp-server-yandex-direct)\n\nMCP-сервер, CLI-утилита и библиотека Pydantic-моделей для [Yandex Direct API v5](https://yandex.ru/dev/direct/doc/concepts/about.html).\n\n- **MCP-сервер** — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами\n- **CLI-утилита** — работа с API из терминала, скрипты и автоматизация\n- **Pydantic-модели** — типизированные модели API для использования в своих Python-программах\n\nВсе данные остаются на вашем компьютере — токен никуда не передаётся.\n\n## Оглавление\n\n- [Архитектура](#архитектура)\n- [Доступные действия](#доступные-действия-79)\n- [MCP-сервер](#mcp-сервер)\n  - [Установка](#установка)\n  - [Подключение к Claude Code](#подключение-к-claude-code)\n  - [Подключение к Claude Desktop](#подключение-к-claude-desktop)\n  - [Подключение через --mcp-config](#подключение-через---mcp-config)\n  - [Примеры](#примеры-mcp)\n- [CLI-утилита](#cli-утилита)\n  - [Установка](#установка-cli)\n  - [Использование](#использование-cli)\n  - [Примеры команд](#примеры-команд)\n- [Pydantic-модели](#pydantic-модели)\n  - [Установка](#установка-библиотеки)\n  - [Использование в своих программах](#использование-в-своих-программах)\n- [Переменные окружения](#переменные-окружения)\n- [Разработка](#разработка)\n- [Лицензия](#лицензия)\n\n## Архитектура\n\nСервер использует паттерн **search + execute** — вместо 79 отдельных инструментов предоставляет 2:\n\n| Инструмент | Описание |\n|------------|----------|\n| `yd_search` | Поиск действий по описанию на естественном языке |\n| `yd_execute` | Выполнение действия по ID |\n\n### Как это работает\n\n```\nLLM: yd_search(\"остановить кампании\")\n→ [{\"id\": \"campaigns-suspend\", \"params_schema\": {\"SelectionCriteria\": {...}, ...}, ...}]\n\nLLM: yd_execute(\"campaigns-suspend\", '{\"SelectionCriteria\": {\"Ids\": [12345]}}')\n→ {\"SuspendResults\": [...]}\n```\n\n## Доступные действия (79)\n\n| Домен | Кол-во | Описание |\n|-------|--------|----------|\n| [`campaigns`](docs/campaigns.md) | 8 | Кампании: создание, управление, архивация |\n| [`adgroups`](docs/adgroups.md) | 4 | Группы объявлений |\n| [`ads`](docs/ads.md) | 9 | Объявления: создание, управление, модерация |\n| [`keywords`](docs/keywords.md) | 6 | Ключевые слова |\n| [`bidding`](docs/bidding.md) | 7 | Ставки и корректировки ставок |\n| [`assets`](docs/assets.md) | 11 | Быстрые ссылки, изображения, видео, расширения |\n| [`audience`](docs/audience.md) | 10 | Аудитории и ретаргетинг |\n| [`negkeywords`](docs/negkeywords.md) | 4 | Общие списки минус-слов |\n| [`feeds`](docs/feeds.md) | 4 | Фиды для динамических объявлений |\n| [`creatives`](docs/creatives.md) | 2 | Креативы для медийных объявлений |\n| [`research`](docs/research.md) | 2 | Исследование ключевых слов |\n| [`leads`](docs/leads.md) | 1 | Лиды из форм лидогенерации |\n| [`changes`](docs/changes.md) | 3 | Отслеживание изменений |\n| [`account`](docs/account.md) | 6 | Аккаунт, справочники, клиенты агентства |\n| [`turbopages`](docs/turbopages.md) | 1 | Турбо-страницы |\n| [`reports`](docs/reports.md) | 1 | Отчёты (TSV/CSV) |\n\n---\n\n## MCP-сервер\n\n### Установка\n\n#### Шаг 1. Получить OAuth-токен\n\n1. Войдите в [Яндекс Директ](https://direct.yandex.ru/)\n2. Перейдите в **Настройки** → **API**\n3. Создайте OAuth-токен с нужными правами\n4. Скопируйте токен\n\n#### Шаг 2. Подключить MCP-сервер\n\n### Подключение к Claude Code\n\n**Способ 1: через uvx** (не требует установки пакета)\n\n> Требуется [uv](https://docs.astral.sh/uv/) — если не установлен:\n> ```bash\n> curl -LsSf https://astral.sh/uv/install.sh | sh\n> ```\n\n```bash\nclaude mcp add yandex-direct \\\n  -e YD_TOKEN=ваш_токен \\\n  -- uvx mcp-server-yandex-direct\n```\n\n**Способ 2: через pip**\n\n```bash\npip install mcp-server-yandex-direct\n\nclaude mcp add yandex-direct \\\n  -e YD_TOKEN=ваш_токен \\\n  -- python -m mcp_server_yandex_direct\n```\n\nДля удаления:\n```bash\nclaude mcp remove yandex-direct\n```\n\n### Подключение к Claude Desktop\n\nДобавьте в конфигурационный файл:\n\n| Клиент | ОС | Путь к файлу |\n|--------|----|-------------|\n| Claude Code | все | `~/.claude/settings.json` (секция `mcpServers`) |\n| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop | Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**Через uvx:**\n```json\n{\n  \"mcpServers\": {\n    \"yandex-direct\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-yandex-direct\"],\n      \"env\": {\n        \"YD_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\n**Через pip** (после `pip install mcp-server-yandex-direct`):\n```json\n{\n  \"mcpServers\": {\n    \"yandex-direct\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server_yandex_direct\"],\n      \"env\": {\n        \"YD_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\n### Подключение через --mcp-config\n\nПодключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном `.env.mcp` файле, а не в конфиге Claude.\n\nИз JSON-строки:\n```bash\nclaude --mcp-config '{\"yandex-direct\":{\"command\":\"bash\",\"args\":[\"-c\",\"source ~/.env.mcp && exec uvx mcp-server-yandex-direct\"]}}'\n```\n\nИз файла:\n```bash\nclaude --mcp-config ~/mcp-servers.json\n```\n\nПример `~/mcp-servers.json`:\n```json\n{\n  \"yandex-direct\": {\n    \"command\": \"bash\",\n    \"args\": [\"-c\", \"source ~/.env.mcp && exec uvx mcp-server-yandex-direct\"]\n  }\n}\n```\n\nПример `~/.env.mcp`:\n```\nYD_TOKEN=ваш_токен\n```\n\n#### Шаг 3. Проверить\n\nПопросите Claude: *«Покажи список кампаний»* — он вызовет `yd_search`, получит схему `campaigns-get`, затем `yd_execute`.\n\n### Примеры (MCP)\n\nClaude автоматически использует `yd_search` для поиска нужного действия, затем `yd_execute` для его выполнения:\n\n- «Покажи все активные кампании» → `yd_search(\"кампании\")` → `yd_execute(\"campaigns-get\", ...)`\n- «Останови кампании 123, 456» → `yd_search(\"остановить кампании\")` → `yd_execute(\"campaigns-suspend\", ...)`\n- «Покажи объявления кампании 789» → `yd_search(\"объявления\")` → `yd_execute(\"ads-get\", ...)`\n- «Добавь ключевую фразу» → `yd_search(\"ключевые слова добавить\")` → `yd_execute(\"keywords-add\", ...)`\n- «Получи справочник регионов» → `yd_search(\"справочники\")` → `yd_execute(\"dictionaries-get\", ...)`\n- «Сделай отчёт по кампаниям за январь» → `yd_search(\"отчёт\")` → `yd_execute(\"reports-get\", ...)`\n\n---\n\n## CLI-утилита\n\n### Установка (CLI)\n\n```bash\npip install mcp-server-yandex-direct\n```\n\nПеременная окружения `YD_TOKEN` должна быть установлена:\n\n```bash\nexport YD_TOKEN=ваш_токен\n```\n\nИли через файл:\n\n```bash\nmcp-server-yandex-direct --env /path/to/.env <command>\n```\n\nФормат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.\n\n### Использование (CLI)\n\nБез аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.\n\n```bash\n# Версия\nmcp-server-yandex-direct --version\n\n# Справка\nmcp-server-yandex-direct --help\nmcp-server-yandex-direct <command> --help\n```\n\n### Примеры команд\n\n```bash\n# Кампании\nmcp-server-yandex-direct campaigns-get '{\"SelectionCriteria\": {}, \"FieldNames\": [\"Id\", \"Name\", \"State\"]}'\nmcp-server-yandex-direct campaigns-suspend 123,456\n\n# Объявления\nmcp-server-yandex-direct ads-get '{\"SelectionCriteria\": {\"CampaignIds\": [123]}, \"FieldNames\": [\"Id\", \"Type\", \"State\"]}'\nmcp-server-yandex-direct ads-moderate 789,101\n\n# Ключевые фразы\nmcp-server-yandex-direct keywords-get '{\"SelectionCriteria\": {\"AdGroupIds\": [111]}, \"FieldNames\": [\"Id\", \"Keyword\", \"State\"]}'\n\n# Справочники\nmcp-server-yandex-direct dictionaries-get Currencies,Regions\n\n# Отчёты\nmcp-server-yandex-direct reports-get '{\"params\": {\"SelectionCriteria\": {\"DateFrom\": \"2026-01-01\", \"DateTo\": \"2026-04-28\"}, \"FieldNames\": [\"Date\", \"CampaignId\", \"Clicks\", \"Cost\"], \"ReportName\": \"My Report\", \"ReportType\": \"CAMPAIGN_PERFORMANCE_REPORT\", \"DateRangeType\": \"CUSTOM_DATE\", \"Format\": \"TSV\"}}'\n```\n\n#### Пример вывода\n\n```bash\n$ mcp-server-yandex-direct campaigns-get '{\"SelectionCriteria\": {\"States\": [\"ON\"]}, \"FieldNames\": [\"Id\", \"Name\"]}'\n{\"Campaigns\": [{\"Id\": 12345, \"Name\": \"Летняя распродажа\"}]}\n```\n\n---\n\n## Pydantic-модели\n\nПакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.\n\n### Установка (библиотеки)\n\n```bash\npip install mcp-server-yandex-direct\n```\n\n### Использование в своих программах\n\n```python\nfrom mcp_server_yandex_direct.models.campaigns import CampaignsGetParams, CampaignsSelectionCriteria\n\n# Валидация данных из API\nparams = CampaignsGetParams(\n    SelectionCriteria=CampaignsSelectionCriteria(States=[\"ON\"]),\n    FieldNames=[\"Id\", \"Name\", \"State\"],\n)\nprint(params.model_dump_json())\n\n# Валидация ответа\nfrom mcp_server_yandex_direct.models.campaigns import CampaignsGetResult\n\ndata = {\"Campaigns\": [{\"Id\": 12345, \"Name\": \"Тест\", \"State\": \"ON\"}]}\nresult = CampaignsGetResult.model_validate(data)\nprint(result.Campaigns[0].Name)  # type-safe доступ к полям\n```\n\nВсе модели используют `extra=\"allow\"` для forward compatibility — неизвестные поля API не вызывают ошибок.\n\nПолный список моделей: [`models/`](src/mcp_server_yandex_direct/models/)\n\n---\n\n## Переменные окружения\n\n| Переменная | Обязательная | По умолчанию | Описание |\n|------------|:------------:|:------------:|----------|\n| `YD_TOKEN` | да | — | OAuth-токен Yandex Direct API |\n| `YD_CLIENT_LOGIN` | нет | — | Логин клиента для агентских аккаунтов |\n| `YD_LANG` | нет | — | Язык ответов: `ru`, `en`, `uk` |\n| `YD_TIMEOUT` | нет | `30` | Таймаут HTTP-запросов к API (секунды) |\n| `YD_FILE_TIMEOUT` | нет | `120` | Таймаут отчётов Reports API (секунды) |\n\n## Разработка\n\n```bash\npip install -e \".[test]\"\nruff check src/ tests/\npytest tests/ -v\n```\n\n## Лицензия\n\nMIT\n",
  "bytes": 9776,
  "sha": "138ff9728a5e5253b2b73ee3dbbb487cf99444c533baf4a9b2ce1fc762226430",
  "repo_slug": "dontsovcmc/mcp-server-yandex-direct",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dontsovcmc_yandex_direct_dbe1007e/readme"
}