yandex-direct-mcp-plugin
Claude Code plugin for managing Yandex.Direct advertising campaigns.
Project Status
The project is implemented and publicly available at
axisrow/yandex-direct-mcp-plugin.
It packages a Python MCP server, Yandex.Direct domain skills, and OAuth helpers
around the direct CLI, which remains the only transport boundary to the
Yandex.Direct API.
Current distribution focus:
- keep the open-source MCP server and core skills free under the MIT license;
- publish installable plugin bundles for Claude Code and Codex-compatible
environments;
- keep the README and generated docs strong enough for public onboarding, demos,
and registry listings;
- reserve paid work for advanced analytics skills, agency integrations,
white-label packaging, and consulting around Yandex.Direct automation.
Features
- MCP Server — structured tools for campaigns, ads, keywords, and reports
- Skills — domain knowledge for Yandex.Direct management and ad copywriting
- OAuth profiles — authentication delegated to direct auth profiles with token + login stored together
Architecture
direct (CLI executable; package: direct-cli) — низкоуровневая утилита (Python), общается с Яндекс.Директ API
↑
MCP Server (Python) — обёртка над CLI, выставляет структурированные инструменты
↑
Skill (SKILL.md) — доменные знания: когда какой инструмент вызвать, лимиты, подводные камни
↑
Plugin (.claude-plugin) — контейнер, объединяющий MCP + скиллы + OAuth в единый пакет
| Компонент | Что это | Что делает | Без него |
|---|
direct (пакет direct-cli) | CLI-утилита (Python) | Выполняет запросы к Яндекс.Директ API | Ничего не работает |
| MCP Server | Процесс (stdio, Python) | Превращает CLI в структурированные инструменты с типизированными параметрами и ответами | Claude собирает bash-команды вручную |
| Skill | Markdown-файл | Учит Claude когда и зачем вызывать инструменты, хранит доменные знания | Claude не знает про лимиты API, батчинг, второй аккаунт |
| Plugin | Директория с манифестом | Упаковывает MCP + скиллы + OAuth для установки одной командой | Нужно настраивать каждый компонент отдельно |
Installation
Codex installable plugin
This repository now includes a Codex marketplace entry and installable plugin bundle:
- Marketplace manifest:
.agents/plugins/marketplace.json
- Plugin bundle:
plugins/yandex-direct/.codex-plugin/plugin.json
Local development
# Run the MCP server directly from the repo
python -m server.main
How the MCP server starts (Linux/macOS)
On SessionStart the hooks/setup.sh hook installs exact-pinned versions
of mcp and direct-cli. The pinned versions live in
scripts/runtime-pins.env — the single source of
truth for both bootstrap channels (Claude Code's hooks/setup.sh and the
Codex bundle's plugins/yandex-direct/run-server.sh).
On Debian/Ubuntu and other externally-managed Pythons (PEP 668) a plain
pip install --user is blocked, so dependencies go into a per-user
virtualenv at ${CLAUDE_PLUGIN_DATA}/venv (default
~/.claude/plugins/data/yandex-direct/venv). On macOS they fall back to user
site-packages.
Bootstrap runs once per (plugin, mcp, direct-cli) triple, not per session.
After the first successful install, hooks/setup.sh writes a stamp file
${CLAUDE_PLUGIN_DATA}/.installed-<plugin>-<mcp>-<direct-cli> and exits
immediately on every later session start — no pip, no network, no import
probe. A new plugin release or a pinned-version bump changes the stamp name
and triggers a single re-install.
.mcp.json therefore does not launch the server with a bare python3
(the system interpreter would not see the venv on Linux). Instead it runs
hooks/run-server.sh, which is the strict consumer of the bootstrap
stamp + venv: if either is missing it exits with an error and asks the user
to restart Claude Code so the SessionStart hook (hooks/setup.sh) can
install the pinned versions. It does not fall back to a bare system
python3 — any random mcp in user site-packages would defeat the
supply-chain pin (#223).
// .mcp.json
{ "mcpServers": { "yandex-direct-mcp": {
"command": "bash",
"args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run-server.sh"]
}}}
Troubleshooting (server fails to start / no tools):
