Yandex MCP

Yandex MCP服务器

🇷🇺 俄语版本

  

MCP（模型上下文协议）服务器 Yandex Direct, Yandex 统计，以及 Yandex Wordstat API。提供 128工具 用于通过任何兼容MCP的客户端管理广告活动、分析、关键字研究和报告。

通过人工智能管理Yandex广告和分析

特性

Yandex Direct API v5（80个工具）

• 活动 --创建、更新、暂停、恢复、存档、删除
• 广告组 --创建、更新目标设置
• 广告 --文本、图像、动态、购物广告适度
• 关键词 --管理关键字和出价
• 统计 --带有异步重试的详细性能报告
• 投标修改人 --移动、桌面、人口统计、区域调整
• 再定向 --重定向列表和受众目标
• 智能广告目标 --基于饲料的目标过滤器
• 网站链接、VCards、标注 --广告扩展
• 图像 --上传、管理和删除广告图片
• 动态 --产品饲料管理
• 视频和创意 --视频广告创作
• 词典 --地区、兴趣、类别
• 否定关键词 --共享否定关键字集

Yandex Wordstat API（5个工具）

• 热门请求 --热门搜索查询和关联
• 动力学 --查询频率随时间的变化趋势
• 区域 --搜索查询的区域分布
• 地区树 --分层区域结构
• 用户信息 -API配额和使用限制

Yandex Metrika API（43种工具）

• 计数器 --创建、配置、删除跟踪计数器
• 目标 --转换目标管理
• 报告 --使用自定义指标、时间序列、比较、深入分析进行分析
• 片段 --受众细分
• 过滤器 --流量过滤规则
• 拨款 --访问权限管理
• 离线数据 --上传转换、通话、费用、用户参数
• 标签和注释 --组织计数器并标记图表事件
• 代表 --账户委托

快速开始

1.安装

git clone https://github.com/SvechaPVL/yandex-mcp.git
cd yandex-mcp
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

2.设置您的Yandex API令牌

创建一个 .env 文件：

YANDEX_TOKEN=your_oauth_token_here

从获取令牌 Yandex OAuth 具有Direct和Metrika API的权限(direct:api, metrika:read, metrika:write).

3.配置您的MCP客户端

添加到MCP客户端设置中：

{
  "mcpServers": {
    "yandex": {
      "command": "python",
      "args": ["-m", "yandex_mcp"],
      "cwd": "/path/to/yandex-mcp",
      "env": {
        "YANDEX_TOKEN": "your_token"
      }
    }
  }
}

4.完成！

> Show all my campaigns in Direct
> Pause campaign 12345
> What are the site stats for the last week?

环境变量

工具（128）

Yandex Direct（80工具）

活动（8）

广告组（3）

广告（12）

关键词（6）

统计学（1）

投标修改人（5）

重新定位和受众目标（9）

智能广告目标（5）

网站链接（3）

视频卡（3）

否定关键字集（4）

广告扩展（3）

视频与创意（4）

饲料（4）

图片（3）

词典和地区（3）

客户与变更（4）

Yandex Metrika（43工具）

柜台（5）

目标（4）

报告（4）

分段（4）

过滤器（4）

赠款（4）

离线数据（5）

标签（6）

注释（4）

代表（3）

Yandex Wordstat（5个工具）

使用示例

活动管理

Show all active campaigns
Pause campaign "Summer sale"
Set weekly budget of campaign 123 to 50000 rubles

关键词

Show keywords in ad group 456
Add keywords "buy iphone" and "iphone price" to group 456
Set bid 50 rubles on keyword 789

分析

Show site stats for the last week
How many conversions on goal "Lead" for the last month?
Show traffic sources for counter 97538360

广告制作

Create a text ad in group 456:
- Title: Buy iPhone 15
- Text: Best prices! Free delivery
- URL: https://example.com/iphone

关键词研究

Show top requests for "buy car from china"
Query dynamics for "electric car" over the last year
Regional distribution for "auto from japan"

备选运行方法

直接执行

python -m yandex_mcp
# or
python main.py

MCP检查员

npx @modelcontextprotocol/inspector python -m yandex_mcp

光标IDE

以与上述相同的格式添加到光标MCP设置中。

项目结构

yandex_mcp/
├── __init__.py          # MCP server init and tool registration
├── client.py            # Async HTTP client for Direct, Metrika & Wordstat APIs
├── config.py            # Configuration and environment variables
├── utils.py             # Error handling utilities
├── models/              # Pydantic input models
│   ├── common.py
│   ├── direct.py
│   ├── direct_extended.py
│   ├── metrika.py
│   ├── metrika_extended.py
│   └── wordstat.py
├── formatters/          # Markdown output formatters
│   ├── direct.py
│   ├── metrika.py
│   └── wordstat.py
└── tools/               # MCP tool definitions
    ├── direct/          # 80 Yandex Direct tools
    │   ├── _helpers.py  # Shared manage-operation factory
    │   ├── campaigns.py
    │   ├── adgroups.py
    │   ├── ads.py
    │   ├── keywords.py
    │   ├── stats.py
    │   ├── images.py
    │   └── ...
    ├── metrika/         # 43 Yandex Metrika tools
    │   ├── counters.py
    │   ├── goals.py
    │   ├── reports.py
    │   └── ...
    └── wordstat.py      # 5 Yandex Wordstat tools

发展

# Install dev dependencies
pip install -e ".[dev]"

# Lint
ruff check .

# Type check
mypy yandex_mcp

# Test
pytest

安全

• 将令牌存储在环境变量中，而不是代码中
• 使用所需的最小权限
• 使用沙盒进行测试(YANDEX_USE_SANDBOX=true)
• 永不承诺 .env 文件

链接

• Yandex Direct API文档
• Yandex Metrika API文档
• 模型上下文协议

许可证

麻省理工学院