Content
# yandex-direct-mcp
Production-grade, open source SDK and [MCP](https://modelcontextprotocol.io) server for the
[Yandex Direct API v5](https://yandex.ru/dev/direct/doc/dg/concepts/about.html).
> **Status:** early development. The transport, authentication, and configuration
> layers, the Campaigns/Keywords/Reports services, and the MCP server are
> implemented and tested. `campaigns.add`/`update` (which require campaign-type-
> specific settings objects) are not yet implemented.
## Goals
- A typed, async-first Python SDK for Yandex Direct API v5.
- An MCP server exposing campaign/keyword/report operations as tools, so LLM
agents (e.g. Claude Desktop) can inspect and manage advertising accounts.
- Strict engineering standards: full type coverage, no stubs, tests for every
module, clean architecture boundaries between transport, services, and MCP tools.
## Installation
```bash
poetry install
```
## Configuration
The client can be configured explicitly or from environment variables:
```python
from yandex_direct import YandexDirectClient, YandexDirectConfig
config = YandexDirectConfig(access_token="<oauth-token>")
# or: config = YandexDirectConfig.from_env()
with YandexDirectClient(config) as client:
...
```
Recognized environment variables:
| Variable | Required | Description |
|----------------------------------------|----------|-----------------------------------------------|
| `YANDEX_DIRECT_ACCESS_TOKEN` | yes | OAuth token for the Yandex Direct application |
| `YANDEX_DIRECT_CLIENT_LOGIN` | no | Client login to act on behalf of (agencies) |
| `YANDEX_DIRECT_USE_OPERATOR_UNITS` | no | Bill points to the operator account |
| `YANDEX_DIRECT_LANGUAGE` | no | Error message language (`ru`, `en`, `uk`) |
| `YANDEX_DIRECT_SANDBOX` | no | Target the API sandbox environment |
## MCP server
The package installs an MCP server exposing campaigns, keywords, and
reports as tools, for use with MCP clients such as Claude Desktop.
Set `YANDEX_DIRECT_ACCESS_TOKEN` (and optionally `YANDEX_DIRECT_CLIENT_LOGIN`,
`YANDEX_DIRECT_SANDBOX`; see [Configuration](#configuration)), then run:
```bash
poetry run yandex-direct-mcp
# or: poetry run python -m yandex_direct.mcp
```
The server communicates over stdio. To use it with Claude Desktop, add it
to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yandex-direct": {
"command": "poetry",
"args": ["run", "yandex-direct-mcp"],
"cwd": "/path/to/yandex-direct-mcp",
"env": { "YANDEX_DIRECT_ACCESS_TOKEN": "<oauth-token>" }
}
}
}
```
Available tools:
| Tool | Description |
|-------------------------|-------------------------------------------------------|
| `list_campaigns` | List campaigns, optionally filtered |
| `suspend_campaigns` | Stop showing ads for the given campaigns |
| `resume_campaigns` | Resume ad delivery for suspended campaigns |
| `archive_campaigns` | Archive stopped campaigns |
| `unarchive_campaigns` | Restore campaigns from the archive |
| `delete_campaigns` | Permanently delete archived campaigns |
| `list_keywords` | List keywords, optionally filtered |
| `add_keywords` | Add keywords to an ad group |
| `update_keyword_bid` | Change a keyword's manual bid |
| `suspend_keywords` | Stop showing ads for the given keywords |
| `resume_keywords` | Resume ad delivery for suspended keywords |
| `delete_keywords` | Permanently delete keywords |
| `get_report` | Fetch a performance report, polling until it's ready |
## Development
```bash
poetry install
ruff check .
black --check .
mypy src
pytest
```
## License
MIT
