Yandex Direct Metrica MCP

yandex直接计量mcp

MCP服务器 Yandex Direct+Yandex Metrica+Yandex Wordstat+Yandex受众 python

网站（文档）：https://georgy-agaev.github.io/yandex-direct-metrica-mcp/

俄罗斯文件：https://georgy-agaev.github.io/yandex-direct-metrica-mcp/ru/

图像：

• GHCR（公开）：https://github.com/georgy-agaev/yandex-direct-metrica-mcp/pkgs/container/yandex-direct-metrica-mcp
• GHCR（专业）：https://github.com/georgy-agaev/yandex-direct-metrica-mcp/pkgs/container/yandex-direct-metrica-mcp-pro
• Docker Hub（可选镜像，如果已配置）：https://hub.docker.com/r/4georgyagaev/yandex-direct-metrica-mcp

主要用户体验目标：

• 提取原始数据进行分析（最小归一化，可追溯输出）。
• 生成一个实用的 BI仪表板（选项1） 作为 HTML + JSON （包括多账户仪表板）。
• 提供 BI选项2（PRO，插件）：数据集+增量同步（仓库/BI管道）。
• 使其易于使用 克劳德代码 通过 claude mcp add.

快速入门（克劳德代码+Docker）

自动设置（推荐）

运行交互式向导--它创建 .env, accounts.json，并为您的客户端注册MCP服务器（Claude Code、Claude Desktop、Cursor、Codex CLI、OpenCode、Gemini CLI）：

python3 scripts/setup.py

或者按照以下手动步骤操作。

1） 准备状态文件夹

为state/config（帐户注册表、缓存等）创建一个本地文件夹：

• 例子： /path/to/mcp-state/yandex-direct-metrica-mcp

创建 accounts.json （多帐户仪表板使用此功能）：

{
  "accounts": [
    {
      "id": "account_ID",
      "name": "account_name",
      "direct_client_login": "direc_client_login",
      "metrica_counter_ids": ["9999999"]
    }
  ]
}

2） 准备 .env

复制 .env.example 转到您的州文件夹并填写：

• Direct/Metrica OAuth凭据
• 受众OAuth凭据（可选）
• Wordstat OAuth凭据（可选）

重要提示： 不要 将秘密提交给git。

3） 将MCP服务器添加到Claude Code

公共（只读，默认安全）：

claude mcp add yandex-direct-metrica-mcp -- \
  docker run --rm -i \
    --env-file /path/to/your/.env \
    -e MCP_ACCOUNTS_FILE=/data/accounts.json \
    -v /path/to/your/state:/data \
    ghcr.io/georgy-agaev/yandex-direct-metrica-mcp:latest

固定到特定版本：

claude mcp add yandex-direct-metrica-mcp -- \
  docker run --rm -i \
    --env-file /path/to/your/.env \
    -e MCP_ACCOUNTS_FILE=/data/accounts.json \
    -v /path/to/your/state:/data \
    ghcr.io/georgy-agaev/yandex-direct-metrica-mcp:v1.0.0

Pro（单独的工件；专为付费用户设计；保持GHCR包的私密性）：

claude mcp add yandex-direct-metrica-mcp-pro -- \
  docker run --rm -i \
    --env-file /path/to/your/.env \
    -e MCP_ACCOUNTS_FILE=/data/accounts.json \
    -v /path/to/your/state:/data \
    ghcr.io/georgy-agaev/yandex-direct-metrica-mcp-pro:v1.0.0

使用本地构建的映像（用于开发）：

docker build -t yandex-direct-metrica-mcp:local .

claude mcp add yandex-direct-metrica-mcp -- \
  docker run --rm -i \
    --env-file /path/to/your/.env \
    -e MCP_ACCOUNTS_FILE=/data/accounts.json \
    -v /path/to/your/state:/data \
    yandex-direct-metrica-mcp:local

笔记：

• docker build ... 产生a 公共只读 默认情况下为图像。
• 如果您真的需要本地PRO映像，请使用以下内容构建：

- docker build --build-arg MCP_EDITION=pro --build-arg MCP_PUBLIC_READONLY=false -t yandex-direct-metrica-mcp:pro . - BI选项2通过专用PRO插件交付；在构建过程中通过安装它 --build-arg MCP_PLUGIN_PIP="..." （参见 docs/pro-plugin.md).

然后：

claude mcp list

4） 生成仪表板（选项1）

提示：“今天”的直接/Metrica数据通常不完整。日常使用，设置 date_to 到 昨天.

询问克劳德代码：

• “生成 dashboard.generate_option1 对于过去30天（截至昨天）的所有帐户，保存到 /path/to/dashboards, all_accounts=true, return_data=false，并给我HTML路径。”

“只读”是什么意思（公共1.0.0合约）

只读意味着：

• 中的受管实体没有更改 直接/音乐/观众 （不创建/更新/删除活动、细分市场、目标等）。

允许的副作用（在公共合同中仍被视为只读）：

• Wordstat 类似报告的请求（提供者端计算）。
• Metrica日志API 用于分析/联接的导出作业(metrica.logs_export)--计数器配置未更改。

公共模式规范：

• docs/public-mode.md

它能做什么？（工具/图层）

此MCP暴露了两层：

1） 原始数据访问（低级工具）

目标是给LLM 完全访问原始报告数据 最小归一化：

• direct.* -Yandex Direct API调用（报表、实体、字典）
• metrica.* -Yandex Metrica API调用（导出、报告）
• wordstat.* -Yandex Wordstat API调用（关键字统计）
• audience.* -Yandex Audience API调用（段、重叠、目录）

输出格式由以下因素控制：

• MCP_CONTENT_MODE=json （建议用于原始分析）

2） 人性化层（高级工具）

这些工具侧重于实用的分析工作流程：

• direct.hf.* --Direct上的“人性化”助手（查找/报告预设、方便查询）
• join.hf.* --Direct+Metrica（UTM/cyclid）之间的最佳合作
• wordstat.hf.* --Wordstat上的关键字建议助手
• audience.hf.* --受众目录+尽力而为的细分市场绩效代理
• dashboard.generate_option1 --生成一个自包含的BI仪表板(HTML + JSON)

3） BI选项2（PRO插件）：数据集+增量同步

BI选项2由可选 私人PRO插件 （不是公共OSS构建的一部分）：

• dashboard.schema
• dashboard.dataset.*
• dashboard.sync.start / dashboard.sync.next （NDJSON友好）

请参阅：

• docs/bi-option2-proposal-2026-02-03.md
• docs/llm-usage-guide-pro-2026-02-03.md

要查看您环境中的完整工具列表：

• 在Claude Code中：询问“列出此MCP服务器的可用工具”（它调用 tools/list).
• 在这个repo中：参见 docs/tool-coverage-2026-01-27.md.

环境变量（高级）

Direct/Metrica OAuth（通常是共享应用程序/令牌）：

• YANDEX_ACCESS_TOKEN 或 YANDEX_REFRESH_TOKEN
• 如果使用刷新： YANDEX_CLIENT_ID, YANDEX_CLIENT_SECRET

Audience OAuth（可以与Direct/Metrica共享，但可以单独使用）：

• YANDEX_AUDIENCE_ACCESS_TOKEN 或 YANDEX_AUDIENCE_REFRESH_TOKEN
• 如果使用刷新： YANDEX_AUDIENCE_CLIENT_ID, YANDEX_AUDIENCE_CLIENT_SECRET

Wordstat OAuth（通常是一个单独的应用程序/令牌）：

• YANDEX_WORDSTAT_ACCESS_TOKEN 或 YANDEX_WORDSTAT_REFRESH_TOKEN
• 如果使用刷新： YANDEX_WORDSTAT_CLIENT_ID, YANDEX_WORDSTAT_CLIENT_SECRET

多帐户注册表：

• MCP_ACCOUNTS_FILE=/data/accounts.json

公共/专业旗帜：

• 公共映像强制只读（默认情况下是安全的），但 MCP_PUBLIC_READONLY=true 仍然是兼容性标志。
• Pro写入需要显式启用：

- MCP_WRITE_ENABLED=true - HF_WRITE_ENABLED=true （HF写入工具） - HF_DESTRUCTIVE_ENABLED=true （删除工具） - 可选安全： MCP_TWO_PHASE_WRITES=true （写入工具返回a confirm_token；执行需要 write.confirm)

• 仅限专业版的身份验证工具（返回机密；无存储）： MCP_AUTH_TOOLS_ENABLED=true

CLI命令

容器/入口点运行MCP服务器（默认为stdio）。本地/虚拟入口点：

• yandex-direct-metrica-mcp （首选）
• mcp-yandex-ad （旧别名）

CLI还提供：

• auth --交互式OAuth助手（打开认证URL并交换代码）

- --flow hybrid （默认）在以下情况下使用环回回调 YANDEX_REDIRECT_URI 是本地URL（例如： http://127.0.0.1:8765/callback)，否则退回到手动代码复制/粘贴。 - 提示：设置 --output-env /path/to/.env 以避免将令牌打印到stdout。

公众vs专业

此回购发货 两件文物:

• 公众： yandex-direct-metrica-mcp （默认情况下为只读）。

- 合同： tests/snapshots/public_tools_v1.json

• 赞成的意见： yandex-direct-metrica-mcp-pro （写入仍然需要显式的环境保护）+私有PRO插件（例如BI选项2）。

请参阅：

• docs/public-vs-pro.md
• docs/compatibility-semver.md

文档（开发人员笔记/项目历史）

• 安装说明： docs/README-setup-2026-01-14.md
• Claude代码设置（本地/dev）： docs/claude-code-setup-2026-01-27.md
• 发布（Docker+注册表）： docs/publishing-docker-2026-01-29.md
• 快速入门： docs/quickstart.md
• 仪表板： docs/dashboard-option1.md
• 观众： docs/audience-2026-02-03.md
• BI选项2（提案，PRO）： docs/bi-option2-proposal-2026-02-03.md
• LLM使用指南（公共只读）： docs/llm-usage-guide-2026-02-03.md
• LLM使用指南（PRO）： docs/llm-usage-guide-pro-2026-02-03.md
• 公众vs专业： docs/public-vs-pro.md
• Claude代码提示示例： examples/claude-code-prompts.md

发展

在本地运行（不使用Docker）：

• python -m venv .venv && .venv/bin/pip install -e .
• .venv/bin/yandex-direct-metrica-mcp --env-file /path/to/.env （首选）
• .venv/bin/mcp-yandex-ad --env-file /path/to/.env （旧别名）

CI和出版：

• CI： .github/workflows/ci.yml
• Docker发布（公开）： .github/workflows/docker-publish-public.yml
• Docker发布（专业版，门控版）： .github/workflows/docker-publish-pro.yml

文件语言

• 英语医生住在 docs/ （这个分支）。
• 俄罗斯医生住在 docs/ru/ （本分支）并发布于 /ru/ 在docs网站上。

免责声明（附属机构/商标）

• 该项目不隶属于Yandex，也不由Yandex背书或赞助。
• Yandex，Yandex。直接，Yandex。Metrica是其各自所有者的商标。

合规性/条款

• 您有责任遵守Yandex Direct API和Yandex Metrica的条款、政策和适用法律。
• 执行Direct和Metrica API调用 代表你 使用您的OAuth凭据；您必须拥有适当的访问权限并接受/遵守相关API条款。
• 外部服务文件/条款（参考）：

- API直接文档： https://yandex.com/dev/direct/ - Metrica API文件： https://yandex.com/dev/metrika/