Yandex Direct MCP server in Ruby
yandex-direct-mcp
A dependency-free, pure Ruby MCP server with 30 tools for Yandex Direct campaigns, ad groups, ads, keywords and reports
High risk
We rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
Why this level
- Creates, edits and archives real ad campaigns and ads
- Manages campaign bids and budget, so an agent mistake causes real spending
Install
Manual install
{
"mcpServers": {
"yandex-direct": {
"command": "ruby",
"args": ["/path/to/yandex-direct-mcp/bin/server"],
"env": {
"YANDEX_DIRECT_TOKEN": "your_oauth_token"
}
}
}
}Add to the project's .mcp.json or the global ~/.claude.json.
This is third-party code. Review the repository files before installing.
What it does
The server wraps the Yandex Direct API v5 into 30 MCP tools across six groups: campaigns (create, edit, archive, pause), ad groups with geo-targeting and negative keywords, text-and-image ads with moderation, keywords and bids, reports on campaigns and search queries, and dictionaries for regions, currencies and audience interests. It is written in pure Ruby with no external dependencies and runs as a local stdio process. A sandbox mode via the YANDEX_DIRECT_SANDBOX variable lets you test without real spending.
Who it is for. For advertisers and agencies who want to run Yandex Direct campaigns directly from a chat with an agent.
Good fit when
- You want to create and edit campaigns, ad groups and ads with natural-language commands
- You want a single MCP with no external dependencies beyond Ruby
- You want to test scenarios in the sandbox before spending real money
Not a fit when
- Your campaigns were created via the simplified SMB wizard: the API does not see them
- You need to upload local images directly: the server only accepts a URL or base64
Example request
Create a Yandex Direct campaign promoting a book with a 500 ruble daily budgetLimitations
You need a Yandex Direct OAuth token and a separate application for full API access via the Tools section; without it the API returns error 58 for incomplete registration. Callouts can be created via the API but can only be attached to an ad through the web interface. Text-and-image ads need a landscape image of at least 1080x607. Ruby must be installed; there is no ready npm or docker package.
How to disable. Remove the yandex-direct block from your project's .mcp.json or from the global ~/.claude.json.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| YANDEX_DIRECT_TOKEN required, secret | OAuth token of the Yandex Direct application |
| YANDEX_DIRECT_SANDBOX | Enables the test API with no real spending |
Security check
- Creates, edits and archives real ad campaigns and ads
- Manages campaign bids and budget, so an agent mistake causes real spending
README in short
The README lists 30 tools across six services, the steps to get an OAuth token and submit the mandatory API access request, configuration for Claude Code and Claude Desktop, API limitations (SMB campaigns are invisible, callouts only via the UI, image requirements) and a sandbox mode for testing. The license is MIT.
FAQ
Are external libraries needed?
No, the server is pure Ruby with no dependencies beyond Ruby itself.
Can I test without real money?
Yes, sandbox mode is enabled with the YANDEX_DIRECT_SANDBOX variable and uses Direct's test API.
Related
Official DataLens (Yandex) skills for Claude Code, Codex and OpenCode: SDK, HTML reports and RLS resolution
A Yandex Metrika MCP server generated from the API spec: 108 methods, 10 tools declared by default, transparent filters and response metadata
An open MCP server and agent skill set for SEO: keyword research, competitors, backlinks and site audits powered by DataForSEO
A Claude Code plugin for SEO audits: technical SEO, E-E-A-T, schema, local and AI search via parallel subagents