Content
<!-- mcp-name: io.github.dontsovcmc/yandex-direct -->
# Tool List
[](https://github.com/dontsovcmc/mcp-server-yandex-direct)
MCP server, CLI utility and Pydantic models library for [Yandex Direct API v5](https://yandex.com/dev/direct/doc/concepts/about.html).
- **MCP Server** — integration with Claude Code, Claude Desktop and other MCP clients
- **CLI Utility** — working with API from terminal, scripts and automation
- **Pydantic Models** — typed API models for use in your Python programs
All data remains on your computer — the token is not transmitted anywhere.
## Table of Contents
- [Architecture](#architecture)
- [Available Actions](#available-actions-79)
- [MCP Server](#mcp-server)
- [Installation](#installation)
- [Connecting to Claude Code](#connecting-to-claude-code)
- [Connecting to Claude Desktop](#connecting-to-claude-desktop)
- [Connecting via --mcp-config](#connecting-via---mcp-config)
- [Examples](#examples-mcp)
- [CLI Utility](#cli-utility)
- [Installation](#installation-cli)
- [Usage](#usage-cli)
- [Command Examples](#command-examples)
- [Pydantic Models](#pydantic-models)
- [Installation](#installation-library)
- [Usage in Your Programs](#usage-in-your-programs)
- [Environment Variables](#environment-variables)
- [Development](#development)
- [License](#license)
## Architecture
The server uses the **search + execute** pattern — instead of 79 separate tools, it provides 2:
| Tool | Description |
|------------|----------|
| `yd_search` | Search for actions by description in natural language |
| `yd_execute` | Execute an action by ID |
### How it Works
```
LLM: yd_search("stop campaigns")
→ [{"id": "campaigns-suspend", "params_schema": {"SelectionCriteria": {...}, ...}, ...}]
LLM: yd_execute("campaigns-suspend", '{"SelectionCriteria": {"Ids": [12345]}}')
→ {"SuspendResults": [...]}
```
## Available Actions (79)
| Domain | Count | Description |
|-------|--------|----------|
| [`campaigns`](docs/campaigns.md) | 8 | Campaigns: creation, management, archivation |
| [`adgroups`](docs/adgroups.md) | 4 | Ad groups |
| [`ads`](docs/ads.md) | 9 | Ads: creation, management, moderation |
| [`keywords`](docs/keywords.md) | 6 | Keywords |
| [`bidding`](docs/bidding.md) | 7 | Bids and bid adjustments |
| [`assets`](docs/assets.md) | 11 | Quick links, images, videos, extensions |
| [`audience`](docs/audience.md) | 10 | Audiences and retargeting |
| [`negkeywords`](docs/negkeywords.md) | 4 | General lists of negative keywords |
| [`feeds`](docs/feeds.md) | 4 | Feeds for dynamic ads |
| [`creatives`](docs/creatives.md) | 2 | Creatives for display ads |
| [`research`](docs/research.md) | 2 | Keyword research |
| [`leads`](docs/leads.md) | 1 | Leads from lead generation forms |
| [`changes`](docs/changes.md) | 3 | Tracking changes |
| [`account`](docs/account.md) | 6 | Account, directories, agency clients |
| [`turbopages`](docs/turbopages.md) | 1 | Turbo pages |
| [`reports`](docs/reports.md) | 1 | Reports (TSV/CSV) |
---
## MCP Server
### Installation
#### Step 1. Get OAuth Token
1. Log in to [Yandex Direct](https://direct.yandex.com/)
2. Go to **Settings** → **API**
3. Create an OAuth token with the required permissions
4. Copy the token
#### Step 2. Connect MCP Server
### Connecting to Claude Code
**Method 1: via uvx** (no package installation required)
> Requires [uv](https://docs.astral.sh/uv/) — if not installed:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
```bash
claude mcp add yandex-direct \
-e YD_TOKEN=your_token \
-- uvx mcp-server-yandex-direct
```
**Method 2: via pip**
```bash
pip install mcp-server-yandex-direct
claude mcp add yandex-direct \
-e YD_TOKEN=your_token \
-- python -m mcp_server_yandex_direct
```
To remove:
```bash
claude mcp remove yandex-direct
```
### Connecting to Claude Desktop
Add to the configuration file:
| Client | OS | File path |
|--------|----|-------------|
| Claude Code | all | `~/.claude/settings.json` (section `mcpServers`) |
| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |
**Via uvx:**
```json
{
"mcpServers": {
"yandex-direct": {
"command": "uvx",
"args": ["mcp-server-yandex-direct"],
"env": {
"YD_TOKEN": "your_token"
}
}
}
}
```
**Via pip** (after `pip install mcp-server-yandex-direct`):
```json
{
"mcpServers": {
"yandex-direct": {
"command": "python",
"args": ["-m", "mcp_server_yandex_direct"],
"env": {
"YD_TOKEN": "your_token"
}
}
}
}
```
### Connecting via --mcp-config
Connects the server only for the duration of one Claude session, without saving to settings. The token is stored in a separate `.env.mcp` file, not in the Claude config.
From JSON string:
```bash
claude --mcp-config '{"yandex-direct":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]}}'
```
From file:
```bash
claude --mcp-config ~/mcp-servers.json
```
Example `~/mcp-servers.json`:
```json
{
"yandex-direct": {
"command": "bash",
"args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]
}
}
```
Example `~/.env.mcp`:
```
YD_TOKEN=your_token
```
#### Step 3. Check
Ask Claude: *«Show list of campaigns»* — it will call `yd_search`, get the `campaigns-get` schema, then `yd_execute`.
### Examples (MCP)
Claude automatically uses `yd_search` to find the required action, then `yd_execute` to execute it:
- «Show all active campaigns» → `yd_search("campaigns")` → `yd_execute("campaigns-get", ...)`
- «Stop campaigns 123, 456» → `yd_search("stop campaigns")` → `yd_execute("campaigns-suspend", ...)`
- «Show ads of campaign 789» → `yd_search("ads")` → `yd_execute("ads-get", ...)`
- «Add keyword phrase» → `yd_search("add keywords")` → `yd_execute("keywords-add", ...)`
- «Get regions directory» → `yd_search("directories")` → `yd_execute("dictionaries-get", ...)`
- «Make a report on campaigns for January» → `yd_search("report")` → `yd_execute("reports-get", ...)`
---
## CLI Utility
### Installation (CLI)
```bash
pip install mcp-server-yandex-direct
```
Environment variable `YD_TOKEN` must be set:
```bash
export YD_TOKEN=your_token
```
Or via file:
```bash
mcp-server-yandex-direct --env /path/to/.env <command>
```
File format — `KEY=VALUE`, one variable per line, `#`-comments.
### Usage (CLI)
Without arguments, the MCP server starts; with a command — CLI. All commands output JSON.
```bash
# Version
mcp-server-yandex-direct --version
# Help
mcp-server-yandex-direct --help
mcp-server-yandex-direct <command> --help
```
### Command Examples
```bash
# Campaigns
mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {}, "FieldNames": ["Id", "Name", "State"]}'
mcp-server-yandex-direct campaigns-suspend 123,456
# Ads
mcp-server-yandex-direct ads-get '{"SelectionCriteria": {"CampaignIds": [123]}, "FieldNames": ["Id", "Type", "State"]}'
mcp-server-yandex-direct ads-moderate 789,101
# Keywords
mcp-server-yandex-direct keywords-get '{"SelectionCriteria": {"AdGroupIds": [111]}, "FieldNames": ["Id", "Keyword", "State"]}'
# Directories
mcp-server-yandex-direct dictionaries-get Currencies,Regions
# Reports
mcp-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"}}'
```
#### Example Output
```bash
$ mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {"States": ["ON"]}, "FieldNames": ["Id", "Name"]}'
{"Campaigns": [{"Id": 12345, "Name": "Summer Sale"}]}
```
---
## Pydantic Models
The package contains typed Pydantic models of all API objects. Models can be used in your Python programs for data validation and autocompletion in IDEs.
### Installation (library)
```bash
pip install mcp-server-yandex-direct
```
### Usage in Your Programs
```python
from mcp_server_yandex_direct.models.campaigns import CampaignsGetParams, CampaignsSelectionCriteria
# Validate data from API
params = CampaignsGetParams(
SelectionCriteria=CampaignsSelectionCriteria(States=["ON"]),
FieldNames=["Id", "Name", "State"],
)
print(params.model_dump_json())
# Validate response
from mcp_server_yandex_direct.models.campaigns import CampaignsGetResult
data = {"Campaigns": [{"Id": 12345, "Name": "Test", "State": "ON"}]}
result = CampaignsGetResult.model_validate(data)
print(result.Campaigns[0].Name) # type-safe access to fields
```
All models use `extra="allow"` for forward compatibility — unknown API fields do not cause errors.
Full list of models: [`models/`](src/mcp_server_yandex_direct/models/)
---
## Environment Variables
| Variable | Required | Default | Description |
|------------|:------------:|:------------:|----------|
| `YD_TOKEN` | yes | — | OAuth token for Yandex Direct API |
| `YD_CLIENT_LOGIN` | no | — | Client login for agency accounts |
| `YD_LANG` | no | — | Response language: `ru`, `en`, `uk` |
| `YD_TIMEOUT` | no | `30` | HTTP request timeout to API (seconds) |
| `YD_FILE_TIMEOUT` | no | `120` | Reports API timeout (seconds) |
## Development
```bash
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v
```
## License
MIT
