ainative-gtm-mcp

@ainative/gtm-mcp

Google Tag Manager 和 Google Ads MCP 服务——审计、修复和管理 GTM 容器及 Google Ads 广告系列、预算、转化、展示位置、地理位置定位，并由 AI Agent（Claude、Cursor 及任何 MCP 客户端）自动应用建议。

属于 AINative 开源工具的一部分。

涵盖 7 个类别的 57 个工具：账号、代码、触发器、审计、版本/发布，以及完整的 Google Ads 生命周期（39 个工具）——端到端地构建、发布、跟踪和调整广告系列：创建广告系列/广告组/响应式搜索广告/响应式展示广告/HTML5 广告、效果最大化广告系列、出价策略与出价控制、广告附加信息（附加链接/宣传信息/结构化摘要/来电）、受众群体、离线 gclid 转化导入、地理位置/语言定位、预算、展示位置，以及自动应用建议——完全通过编程实现，无需使用界面。

关键词： google tag manager mcp、google ads mcp、gtm mcp server、google ads api mcp、conversion tracking mcp、campaign budget management、negative placement / click-fraud exclusion、geo targeting、auto-apply recommendations、recommendation subscriptions、conversion goals、Smart Bidding、PPC automation、ad spend control、Claude MCP、model context protocol、AI agent advertising tools。

快速开始

1. 安装

# Claude Code (recommended)
claude mcp add ainative-gtm-mcp npx -- -y @ainative/gtm-mcp \
  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json

# Or run directly
npx @ainative/gtm-mcp

2. 设置 Google Cloud 身份验证

此服务通过拥有 Tag Manager API 访问权限的 Google Cloud 服务账号进行身份验证。没有浏览器 OAuth 流程——专为无头/Agent 使用场景设计。

第 1 步 — 启用 Tag Manager API

1. 前往 Google Cloud Console
2. 选择或创建一个项目
3. 前往 APIs & Services → Library
4. 搜索 Tag Manager API（tagmanager.googleapis.com），然后点击 Enable

第 2 步 — 创建服务账号

1. 前往 IAM & Admin → Service Accounts
2. 点击 Create Service Account
3. 为其命名（例如 gtm-mcp-agent）
4. 跳过 GCP 级别的角色分配——GTM 有自己的权限系统
5. 点击 Done，然后打开该服务账号
6. 前往 Keys → Add Key → Create new key → JSON
7. 下载 JSON 密钥文件——妥善保管

第 3 步 — 在 GTM 中授予服务账号访问权限

大多数人会漏掉这一步。除了在 GCP 中设置权限，还需要在 Google Tag Manager 内部单独添加该 GCP 服务账号为用户：

1. 前往 tagmanager.google.com
2. 点击 Admin（顶部导航栏）
3. 在 Account 下，点击 User Management
4. 点击 + → Add users
5. 输入服务账号邮箱（例如 [email protected]）
6. 将权限设为 Publish（编辑和发布代码所需）
7. 保存

注意： 如果只需要读取权限（用于审计），Read 权限就足够了。

第 4 步 — 配置环境变量

export GTM_SERVICE_ACCOUNT_KEY_PATH="/path/to/service-account.json"

# Or use inline JSON (useful for CI/CD)
export GTM_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

# Or use Application Default Credentials
gcloud auth application-default login

3. 连接到 Claude Code

claude mcp add ainative-gtm-mcp npx -- -y @ainative/gtm-mcp \
  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json

或者在项目根目录添加 .mcp.json：

{
  "mcpServers": {
    "ainative-gtm-mcp": {
      "command": "npx",
      "args": ["-y", "@ainative/gtm-mcp"],
      "env": {
        "GTM_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json"
      }
    }
  }
}

安全： 如果 .mcp.json 包含密钥路径，请将其添加到 .gitignore。使用 .mcp.example.json 作为团队成员的模板。

4. 验证是否正常运行

向 Claude 提问：

List my GTM accounts

预期结果：你的 GTM 账号名称和 ID。如果得到空数组 []，说明服务账号尚未添加到 GTM（见上文第 3 步）。

---

重要提示：GTM 与 Google Ads 转化

此 MCP 服务管理 Google Tag Manager 容器——代码、触发器、变量和发布。

如果你在 GA4 中看到 ads_conversion_PURCHASE_1 之类的事件，它们可能来自 Google Ads 自动导入的转化（通过关联 GA4 与 Google Ads 账号），而不是 GTM 代码。此时：

• 如果事件由 GTM 代码触发 → 使用 gtm_find_misfiring_conversion_tags 修复
• 如果事件是从 GA4 导入的 Google Ads 转化 → 在 Google Ads → Tools → Conversions 中修复，而不是在 GTM 中修复

要区分二者：如果你的 GTM 容器没有任何代码（gtm_list_tags 返回 []），则转化事件来自 GTM 之外。

---

示例：修复触发异常的转化代码

最常见的 GTM 计费问题：Google Ads 转化代码在每次页面浏览时都会触发，而不是仅在购买确认时触发。

1. List your accounts:
   "List my GTM accounts"
   → accountId: 123456789

2. List containers:
   "List containers for account 123456789"
   → containerId: 987654321, publicId: GTM-XXXXXXX

3. Audit the container:
   "Audit container 987654321 in account 123456789"
   → health score, list of issues including misfiring tags

4. Find misfiring conversion tags:
   "Find misfiring conversion tags in container 987654321"
   → shows which tags fire on All Pages instead of specific events

5. Fix the tag:
   "Fix tag 42 to only fire on the purchase_confirmed event"
   → gtm_fix_conversion_tag_trigger creates a scoped Custom Event trigger
     and rewires the tag automatically

6. Review and publish:
   "Show pending workspace changes, then publish"
   → gtm_get_workspace_status + gtm_publish

---

工具参考

账号与容器（3 个工具）

工具	描述
gtm_list_accounts	列出所有可访问的 GTM 账号
gtm_list_containers	列出账号中的容器
gtm_get_container	获取容器详情

代码（4 个工具）

工具	描述
gtm_list_tags	列出工作区中的所有代码
gtm_get_tag	获取完整的代码配置
gtm_update_tag	更新代码（触发器、参数、名称）
gtm_delete_tag	删除代码

触发器（4 个工具）

工具	描述
gtm_list_triggers	列出所有触发器
gtm_get_trigger	获取触发器配置
gtm_create_trigger	创建新触发器
gtm_update_trigger	更新现有触发器

审核与修复（3 个工具）

工具	描述
gtm_audit_container	全面审核容器——健康评分 0–100，列出问题
gtm_find_misfiring_conversion_tags	查找在“所有页面”上触发、而非在特定事件上触发的转化代码
gtm_fix_conversion_tag_trigger	修复触发异常的代码——创建范围限定的自定义事件触发器，并重新关联代码

版本与发布（4 个工具）

工具	描述
gtm_list_workspaces	列出工作区
gtm_get_workspace_status	查看发布前的待处理更改
gtm_create_version	根据工作区更改创建命名版本
gtm_publish	将工作区发布到线上

Google Ads（39 个工具）

完整的程序化广告系列生命周期——Agent 无需使用 UI，即可端到端地构建、启动、衡量和优化广告系列。

构建（广告系列、广告组、广告、素材资源）

工具	描述
gads_create_campaign	创建 Search/Display 广告系列，并配置专用预算和正确的网络设置
gads_create_pmax_campaign	一键构建 Performance Max——通过一次调用创建广告系列、预算和素材资源组（标题、描述、图片、徽标）；Google AI 会针对 Search/Display/YouTube/Gmail 进行优化
gads_create_ad_group	在广告系列中创建广告组
gads_create_responsive_search_ad	创建 RSA（3–15 个标题、2–4 条描述，并验证长度）
gads_create_responsive_display_ad	创建自适应展示广告
gads_create_html5_ad	根据媒体包创建 HTML5 上传版（动画）展示广告
gads_upload_image_asset	通过 URL 上传图片素材资源
gads_upload_media_bundle	上传 HTML5 媒体包（zip）素材资源

出价策略与出价

工具	描述
gads_set_bidding_strategy	切换出价策略（尽可能争取更多点击 / 尽可能提高转化次数 / 目标 CPA / 目标 ROAS / 手动 CPC）——会回读更改以确认已生效（空载荷切换会静默地不执行任何操作）
gads_set_ad_group_bid	设置广告组的默认最高 CPC 出价
gads_set_keyword_bid	设置特定关键字的最高 CPC 出价

广告控制

工具	描述
gads_set_ad_status	暂停 / 启用 / 移除单个广告
gads_request_ad_review	对遭拒或受限的广告请求重新审核（申诉），适用于可通过 API 申诉的情况；对于仅限 UI 处理的政策主题，会如实返回结果

广告附加信息（素材资源）

工具	描述
gads_add_sitelink	创建并附加网站链接
gads_add_callout	创建并附加宣传信息（例如“7 天免费试用”）
gads_add_structured_snippet	创建并附加结构化摘要
gads_add_call_extension	创建并附加电话附加信息

受众群体与转化（归因）

工具	描述
gads_add_audience_to_ad_group	附加用户列表受众（观察或定位）
gads_create_conversion_action	创建离线转化（UPLOAD_CLICKS）操作，用于导入 gclid
gads_upload_click_conversion	上传以 gclid 为键的离线转化 — 将实际注册归因到带来该注册的广告点击

转化与报告

工具	描述
gads_list_conversion_actions	列出所有转化操作 — 名称、ID、计数类型、状态、类别
gads_update_conversion_counting	修正转化操作的计数类型（ONE_PER_CLICK 与 MANY_PER_CLICK）
gads_audit_conversion_goals	审核所有转化目标 — 找出计数配置错误或未启用的转化
gads_set_conversion_goal_inclusion	将转化操作纳入或排除主要「转化」指标和智能出价（例如，停止 PAGE_VIEW 操作虚增转化次数）
gads_get_account_performance	账户级效果 — 按日期范围显示展示次数、点击次数、费用和转化次数

广告系列与预算

工具	描述
gads_update_campaign_budget	设置广告系列的每日预算（提高或降低支出）
gads_pause_campaign	暂停广告系列 — 立即停止投放广告
gads_create_keyword	向广告组添加关键词
gads_remove_keyword	从广告组移除（暂停）关键词

定位与欺诈防护

工具	描述
gads_remove_campaign_criterion	按 ID 移除广告系列条件（定位的地理位置／版位／关键词）— 例如，停止定位带来无效流量的国家／地区
gads_add_negative_placement	排除网站／应用版位（屏蔽测验农场和垃圾应用等点击欺诈网站）
gads_add_geo_target	添加地理位置定位（默认仅限实际所在位置 — 可防范印度欺诈的设置）
gads_set_presence_only	强制广告系列使用仅限实际所在位置的地理位置定位
gads_add_negative_keyword	添加广告系列级否定关键词
gads_add_language_target	为广告系列添加语言定位

自动应用建议

工具	描述
gads_list_recommendation_subscriptions	列出自动应用建议订阅及其状态（审核自动应用的内容）
gads_set_recommendation_subscription	开启／关闭自动应用建议（暂停可能在无提示的情况下提高支出的预算／出价建议）

Google Ads 身份验证

Google Ads 工具使用 OAuth2 凭据。通过环境变量或 ADC 文件提供凭据：

# Option A: Explicit env vars
export GADS_CLIENT_ID="your-client-id"
export GADS_CLIENT_SECRET="your-client-secret"
export GADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

# Option B: Use Application Default Credentials (gcloud OAuth)
# Run: gcloud auth application-default login
# The server reads ~/.config/gcloud/application_default_credentials.json automatically
export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

开发者令牌： 在 Google Ads API Center 获取。测试令牌适用于沙盒账户；生产环境需要标准令牌。

关于从 GA4 导入的转化的说明： 如果你在 GA4 中看到 ads_conversion_PURCHASE_1 等事件，但 gads_list_conversion_actions 返回空列表，说明这些转化是导入 Google Ads 的 GA4 转化（在 Google Ads → 工具 → 转化中配置）。它们不是独立的转化操作，必须通过 Google Ads 界面进行管理。

---

故障排除

症状	原因	解决方法
gtm_list_accounts 返回 []	GTM 中未添加服务账号	在 GTM → 管理 → 用户管理中添加服务账号电子邮件地址
出现 Tag Manager API has not been used 错误	未启用 API	前往 console.cloud.google.com → API 和服务 → Tag Manager API 启用
更新代码时出现 Permission denied	服务账号只有只读权限	在 GTM 用户管理中将权限升级为发布权限
gtm_list_tags 返回 []	工作区为空（未发布任何代码）	检查其他 workspaceId，或确认 GTM 信息中心中是否存在代码
GA4 中有转化事件，但没有匹配的 GTM 代码	事件来自 Google Ads 自动导入	在 Google Ads → 工具 → 转化中修复，而不是在 GTM 中修复

---

开发

git clone https://github.com/AINative-Studio/core
cd packages/mcp-servers/ainative-gtm-mcp
npm install
npm run build
npm run dev

许可证

MIT — AINative Studio