gtm-ga4

mcp-gtm-ga4

用于 Google Tag Manager 和 GA4 的 MCP 服务，可通过 Claude 进行标签管理、同意审计、工作区版本管理和分析报告。

功能

• 14 个工具，涵盖 GTM 工作区管理（标签、触发器、变量）、同意合规审计、工作区预览与版本管理，以及 GA4 报告
• 沙盒安全性——所有写入操作都会验证目标是否为已解析的工作区，并拒绝写入非沙盒工作区
• 支持多个客户端——可通过环境变量按客户端配置
• 自动检测 Default Workspace ID——除非使用自定义沙盒，否则无需手动指定工作区 ID

安装

npm install mcp-gtm-ga4

或者克隆并构建：

git clone https://github.com/mharnett/mcp-gtm-ga4.git
cd mcp-gtm-ga4
npm install
npm run build

配置

**安全提示：**切勿分享 .mcp.json 文件或将其提交到 git——其中可能包含 API 凭据。请将 .mcp.json 添加到 .gitignore。

运行时通过环境变量配置。

变量	必填	说明
GOOGLE_APPLICATION_CREDENTIALS	是	Google 凭据 JSON 密钥文件的路径（服务账号或已授权用户——参见下文的身份验证）
GTM_ACCOUNT_ID	是	GTM 账号 ID
GTM_CONTAINER_ID	是	GTM 容器 ID
GA4_PROPERTY_ID	是	GA4 属性 ID
GTM_SANDBOX_WORKSPACE_ID	否	覆盖工作区 ID（若省略，则自动检测 Default Workspace）
MCP_SERVER_NAME	否	服务名称（默认使用包名称 mcp-gtm-ga4）

请参阅 config.example.json 了解参考模板。唯一从磁盘读取的值是 oauth.scope（位于可选的 config.json 中）——它是 OAuth 引导流程请求的 OAuth 作用域的唯一事实来源。如果没有 config.json，则使用仓库中提交的最小作用域。

身份验证

此 MCP 支持两种身份验证模式。两者都使用相同的 GOOGLE_APPLICATION_CREDENTIALS 运行时路径。

优先级与机制

没有运行时的服务账号与 OAuth 切换选项。两种模式最终都会汇入同一个位置——GOOGLE_APPLICATION_CREDENTIALS——运行时会将其传递给 GoogleAuth({ keyFile })。此环境变量指向的文件就是凭据：

• 服务账号 JSON 密钥（以下选项 1），或
• auth 子命令写入的 authorized_user 密钥文件（选项 2）——该文件使用完全相同的位置。

因此，唯一实际的优先级规则是故障处理：使用显式配置的密钥文件；若未设置 GOOGLE_APPLICATION_CREDENTIALS，服务启动时会明确报错，并在引导错误中同时指出服务账号路径和 auth OAuth 助手。它会刻意避免回退到 Google Application Default Credentials（gcloud 用户凭据／GCE 元数据服务）——不会静默使用机器本地默认凭据，也不会在运行时静默切换凭据。

1. 服务账号（主要方式，推荐用于无人值守／服务端场景）

在 GCP 项目中创建服务账号，下载其 JSON 密钥，授予其 GTM 容器角色（针对目标 GTM 容器）和 GA4 属性访问权限，然后将 GOOGLE_APPLICATION_CREDENTIALS 指向该密钥文件。无需 OAuth 流程、浏览器或刷新令牌。这是无头／服务端／无人值守部署的推荐方式。

2. 用户 OAuth（交互式，适用于没有服务账号的用户）

如果无法使用服务账号，请使用你自己的 Google OAuth 客户端生成用户凭据（在你自己的 GCP 项目中创建的“桌面应用” OAuth 2.0 客户端 ID——启用 Tag Manager API 和 Google Analytics Admin + Data API）。以下两个等效的引导命令都使用 PKCE（RFC 7636，S256）强化安全性，并且都会请求 config.json（oauth.scope）中的作用域，以确保两者始终一致：

export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=your-client-secret

# Option A: write an authorized_user credential file directly
node dist/index.js auth --output ./gtm-ga4-credentials.json
# then set GOOGLE_APPLICATION_CREDENTIALS=./gtm-ga4-credentials.json

# Option B: the standalone helper (prints GOOGLE_REFRESH_TOKEN + a ready-to-save
# authorized_user JSON you can write to a file for GOOGLE_APPLICATION_CREDENTIALS)
node get-refresh-token.cjs

刷新令牌／凭据由你写入，并且只从你的环境中读取。不会共享任何内容，也不会捆绑 OAuth 客户端密钥文件。不要将助手的标准输出重定向到共享日志——按设计，刷新令牌会输出到标准输出。

请求的 OAuth scopes

入门流程仅请求此 MCP 工具使用的 scopes（来自 config.example.json → oauth.scope）：

Scope	使用方
tagmanager.edit.containers	gtm_create_tag、gtm_update_tag、gtm_create_variable、gtm_update_variable、gtm_delete_variable、标签/触发器/变量读取
tagmanager.edit.containerversions	gtm_create_version
tagmanager.publish	gtm_create_version、gtm_preview（快速预览）
analytics.readonly	gtm_ga4_run_report、gtm_ga4_realtime_report、gtm_ga4_list_custom_dimensions
analytics.edit	gtm_ga4_create_custom_dimension

有意不请求 tagmanager.readonly——编辑 scopes 已授予读取权限。

使用方法

Claude Code（.mcp.json）

{
  "mcpServers": {
    "gtm-ga4": {
      "command": "node",
      "args": ["/path/to/mcp-gtm-ga4/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GTM_ACCOUNT_ID": "1234567890",
        "GTM_CONTAINER_ID": "9876543",
        "GA4_PROPERTY_ID": "331956119"
      }
    }
  }
}

npx

GTM_ACCOUNT_ID=1234567890 \
GTM_CONTAINER_ID=9876543 \
GA4_PROPERTY_ID=331956119 \
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json \
npx mcp-gtm-ga4

Claude Desktop： 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

安全性

工作区沙箱保护

所有写入操作（gtm_update_tag、gtm_create_tag、gtm_preview、gtm_create_version）都会在执行前验证目标是否为已解析的工作区。如果请求尝试写入其他工作区，服务会返回 SafetyError 并阻止该操作。

这可以防止 MCP 服务配置为沙箱工作区时意外更改生产环境。

工具

GTM 标签

工具	描述
gtm_list_tags	列出工作区中的所有标签，包括同意状态和触发条件
gtm_get_tag	根据标签 ID 获取完整的标签配置
gtm_update_tag	更新现有标签（通过 JSON 合并补丁）
gtm_create_tag	根据 JSON 定义创建新标签

GTM 结构

工具	描述
gtm_list_triggers	列出所有触发器（ID、名称、类型）
gtm_list_variables	列出所有变量（ID、名称、类型）

GTM 同意

工具	描述
gtm_audit_consent	审核所有标签的同意配置是否合规

GTM 工作区

工具	描述
gtm_preview	生成当前工作区的快速预览
gtm_create_version	根据工作区创建新的容器版本

GA4 报告

工具	描述
gtm_ga4_run_report	使用维度、指标、日期范围和筛选条件运行 GA4 报告
gtm_ga4_realtime_report	运行 GA4 实时报告（最近 30 分钟）

GA4 管理

工具	描述
gtm_ga4_list_custom_dimensions	列出媒体资源的所有自定义维度
gtm_ga4_create_custom_dimension	创建新的自定义维度

架构

• GTM API：googleapis（Tag Manager v2）
• GA4 数据：@google-analytics/data（BetaAnalyticsDataClient）
• GA4 管理：@google-analytics/admin（AnalyticsAdminServiceClient）
• 弹性机制：cockatiel（重试、断路器、超时策略）
• 日志记录：pino 与 pino-pretty
• 传输：MCP SDK stdio 传输

许可证

MIT

作者

由 Mark Harnett / drak-marketing 构建