使用说明

Yandex MCP服务器

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

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

特性

Yandex Direct API v5（80个工具）

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

Yandex Wordstat API（5个工具）

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

Yandex网站管理员API v4（4个工具）

用户ID --解析令牌所有者的网站管理员用户ID
主机 --列出已验证的站点及其ID
主机摘要 --SQI、可搜索和排除的页面数
热门查询 --包含展示、点击和位置的有机搜索查询

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?

环境变量

变量	必填	描述
`YANDEX_TOKEN`	是	Yandex OAuth令牌（用于Direct和Metrika）
`YANDEX_DIRECT_TOKEN`	否	直接API的单独令牌
`YANDEX_METRIKA_TOKEN`	否	Metrika API的独立令牌
`YANDEX_CLIENT_LOGIN`	否	代理帐户的客户端登录
`YANDEX_USE_SANDBOX`	否	设置为 `true` 用于沙箱API
`YANDEX_WORDSTAT_API_KEY`	对于Wordstat	Yandex云服务帐户API密钥（搜索API v2）；旧的OAuth Wordstat API已停用
`YANDEX_CLOUD_FOLDER_ID`	否	用于搜索API v2请求的Yandex Cloud文件夹ID（可选）

工具（132）

Yandex Direct（80工具）

活动（8）

工具	说明
`direct_get_campaigns`	获取包含状态、策略和预算信息的活动
`direct_create_campaign`	创建新的活动（搜索、网络或两者兼而有之）
`direct_update_campaign`	更新活动设置（策略、预算、时间表、地区、归因模型）
`direct_suspend_campaigns`	暂停活动
`direct_resume_campaigns`	恢复暂停的活动
`direct_archive_campaigns`	存档活动
`direct_unarchive_campaigns`	恢复已存档的活动
`direct_delete_campaigns`	永久删除活动

广告组（3）

工具	说明
`direct_get_adgroups`	获取具有目标设置的广告组
`direct_create_adgroup`	在广告系列中创建新的广告组
`direct_update_adgroup`	更新广告组设置和目标

广告（12）

工具	说明
`direct_get_ads`	获取包含内容和审核状态的广告
`direct_create_text_ad`	创建包含标题、文本和URL的文字广告
`direct_create_image_ad`	创建图像广告（横幅）
`direct_create_dynamic_ad`	从提要数据创建动态文本广告
`direct_create_shopping_ad`	创建购物广告（统一的活动格式）
`direct_update_ad`	更新广告内容（触发重新审核）
`direct_moderate_ads`	提交广告进行审核
`direct_suspend_ads`	暂停广告
`direct_resume_ads`	恢复暂停的广告
`direct_archive_ads`	存档广告
`direct_unarchive_ads`	恢复已存档的广告
`direct_delete_ads`	永久删除广告

关键词（6）

工具	说明
`direct_get_keywords`	获取带有出价和状态的关键字
`direct_add_keywords`	将关键字添加到广告组
`direct_set_keyword_bids`	设置搜索和网络出价
`direct_suspend_keywords`	暂停关键字
`direct_resume_keywords`	恢复暂停的关键字
`direct_delete_keywords`	永久删除关键字

统计学（1）

工具	说明
`direct_get_statistics`	获取绩效报告（印象、点击、成本、点击率）

投标修改人（5）

工具	说明
`direct_get_bid_modifiers`	获取出价修改器（移动、桌面、人口统计、区域）
`direct_add_bid_modifier`	向活动或广告组添加出价修改器
`direct_set_bid_modifier`	设置投标修改值（0-1300%）
`direct_delete_bid_modifiers`	删除投标修改人
`direct_toggle_bid_modifiers`	启用或禁用出价修改器

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

工具	说明
`direct_get_retargeting_lists`	根据Metrika目标获取重定向列表
`direct_add_retargeting_list`	使用目标规则创建重定向列表
`direct_update_retargeting_list`	更新重定向列表规则
`direct_delete_retargeting_lists`	删除重定向列表
`direct_get_audience_targets`	获取受众目标，将列表链接到广告组
`direct_add_audience_target`	将受众目标添加到广告组
`direct_suspend_audience_targets`	暂停目标受众
`direct_resume_audience_targets`	恢复受众目标
`direct_delete_audience_targets`	删除目标受众

智能广告目标（5）

工具	说明
`direct_get_smart_ad_targets`	获取智能广告目标过滤器和条件
`direct_add_smart_ad_target`	向智能广告组添加目标过滤器
`direct_suspend_smart_ad_targets`	暂停智能广告目标
`direct_resume_smart_ad_targets`	恢复智能广告目标
`direct_delete_smart_ad_targets`	删除智能广告目标

网站链接（3）

工具	说明
`direct_get_sitelinks`	获取站点链接集
`direct_add_sitelinks`	创建一个站点链接集（最多8个链接）
`direct_delete_sitelinks`	删除站点链接集

视频卡（3）

工具	说明
`direct_get_vcards`	获取名片信息（地址、电话、营业时间）
`direct_add_vcard`	制作广告名片
`direct_delete_vcards`	删除名片

否定关键字集（4）

工具	说明
`direct_get_negative_keyword_shared_sets`	获取共享的否定关键字集
`direct_add_negative_keyword_shared_set`	创建共享的否定关键字集
`direct_update_negative_keyword_shared_set`	更新否定关键字集
`direct_delete_negative_keyword_shared_sets`	删除负面关键字集

广告扩展（3）

工具	说明
`direct_get_adextensions`	获取广告扩展（标注等）
`direct_add_callouts`	添加详图索引扩展名
`direct_link_callouts_to_ad`	将公告链接到广告

视频与创意（4）

工具	说明
`direct_upload_video`	上传用于广告扩展的视频
`direct_get_advideos`	获取上传的广告视频
`direct_create_video_creative`	从上传的视频中创建视频创意
`direct_get_creatives`	获取视频创意

饲料（4）

工具	说明
`direct_get_feeds`	获取产品订阅源
`direct_add_feed`	添加产品提要（URL或文件）
`direct_update_feed`	更新订阅源设置
`direct_delete_feeds`	删除订阅源

图片（3）

工具	说明
`direct_upload_image`	上传base64编码的图像（JPEG、GIF、PNG）
`direct_get_images`	获取图像元数据、哈希值和关联状态
`direct_delete_images`	按哈希删除未关联的图像

词典和地区（3）

工具	说明
`direct_get_dictionaries`	获取Direct词典（广告类别、兴趣）
`direct_get_regions`	获取地理区域树
`direct_get_interests`	获取目标兴趣类别

客户与变更（4）

工具	说明
`direct_get_client_info`	获取帐户信息和设置
`direct_check_campaign_changes`	检查特定活动的变化
`direct_check_all_changes`	检查帐户是否有任何更改
`direct_get_recent_changes_timestamp`	获取最近更改的时间戳

Yandex Metrika（43工具）

柜台（5）

工具	说明
`metrika_get_counters`	列出所有Metrika计数器
`metrika_get_counter`	获取详细的计数器信息（代码状态、webvisor、目标）
`metrika_create_counter`	使用跟踪代码创建新计数器
`metrika_update_counter`	更新计数器名称、站点或收藏夹状态
`metrika_delete_counter`	删除计数器及其所有数据

目标（4）

工具	说明
`metrika_get_goals`	获取计数器的转换目标
`metrika_create_goal`	创建目标（URL、事件、复合等）
`metrika_update_goal`	更新目标条件
`metrika_delete_goal`	删除目标

报告（4）

工具	说明
`metrika_get_report`	获取具有自定义指标和维度的分析报告
`metrika_get_report_by_time`	获取时间序列报告（每日、每周、每月）
`metrika_get_comparison_report`	比较两个日期范围
`metrika_get_drilldown_report`	获取分层深入报告

分段（4）

工具	说明
`metrika_get_segments`	获取受众细分
`metrika_create_segment`	使用筛选表达式创建分段
`metrika_update_segment`	更新分段定义
`metrika_delete_segment`	删除分段

过滤器（4）

工具	说明
`metrika_get_filters`	获取计数器的数据筛选器
`metrika_create_filter`	创建筛选器（包括/排除流量）
`metrika_update_filter`	更新过滤条件
`metrika_delete_filter`	删除筛选器

赠款（4）

工具	说明
`metrika_get_grants`	获取计数器的访问权限
`metrika_add_grant`	授予其他用户访问权限
`metrika_update_grant`	更新授权权限
`metrika_delete_grant`	撤销访问权限

离线数据（5）

工具	说明
`metrika_upload_offline_conversions`	上传离线转换数据
`metrika_get_offline_conversions_status`	检查上传处理状态
`metrika_upload_calls`	上传通话跟踪数据
`metrika_upload_expenses`	上传广告费用数据
`metrika_upload_user_parameters`	上传自定义用户参数

标签（6）

工具	说明
`metrika_get_labels`	获取用于组织计数器的标签
`metrika_create_label`	创建标签
`metrika_update_label`	重命名标签
`metrika_delete_label`	删除标签
`metrika_link_counter_to_label`	将计数器链接到标签
`metrika_unlink_counter_from_label`	取消计数器与标签的链接

注释（4）

工具	说明
`metrika_get_annotations`	获取计数器的图表注释
`metrika_create_annotation`	创建注释（在图表上标记事件）
`metrika_update_annotation`	更新注释文本
`metrika_delete_annotation`	删除注释

代表（3）

工具	说明
`metrika_get_delegates`	获取帐户代理列表
`metrika_add_delegate`	添加具有计数器访问权限的代理
`metrika_delete_delegate`	删除代理

Yandex Wordstat（5个工具）

工具	说明
`wordstat_top_requests`	获取热门搜索查询和短语关联
`wordstat_dynamics`	获取随时间变化的查询频率动态（每日/每周/每月）
`wordstat_regions`	获取搜索查询的区域分布
`wordstat_regions_tree`	获取带有ID的完整分层区域树
`wordstat_user_info`	弃用：删除v1配额终结点；返回指向Yandex Cloud控制台的指针

Yandex网站管理员（4个工具）

工具	说明
`webmaster_get_user_id`	解析令牌所有者的网站管理员用户ID
`webmaster_get_hosts`	列出已验证的站点及其主机ID
`webmaster_get_host_summary`	获取SQI、可搜索和排除的页面数
`webmaster_get_popular_queries`	通过展示、点击、位置获取自然搜索查询

使用示例

活动管理

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 & Webmaster 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
│   └── webmaster.py
├── formatters/          # Markdown output formatters
│   ├── direct.py
│   ├── metrika.py
│   ├── wordstat.py
│   └── webmaster.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
    └── webmaster.py     # 4 Yandex Webmaster tools

发展

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

# Lint
ruff check .

# Type check
mypy yandex_mcp

# Test
pytest