内容
# GTM MCP 服务器
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://go.dev/)
[](https://modelcontextprotocol.io)
[](https://claude.ai)
[](https://chatgpt.com)
[](https://geminicli.com)
[](https://cursor.com)
[](https://github.com/paolobietolini/gtm-mcp-server)
[](https://github.com/paolobietolini/gtm-mcp-server)
**让 AI 管理您的 Google Tag Manager 容器。**
通过与 Claude、ChatGPT、Gemini、Cursor 等 AI 助手进行自然对话，创建标签、审核配置、生成跟踪计划并发布更改。
**网址：** `https://mcp.gtmeditor.com`
---
## 目录
- [支持的 AI 客户端](#支持的-ai-客户端)
- [您可以做什么？](#您可以做什么？)
- [快速入门](#快速入门)
- [Claude（网页和桌面端）](#claude网页和桌面端)
- [ChatGPT](#chatgpt)
- [Gemini CLI](#gemini-cli)
- [Cursor](#cursor)
- [功能](#功能)
- [标签管理](#标签管理)
- [触发器管理](#触发器管理)
- [容器操作](#容器操作)
- [服务器端容器](#服务器端容器)
- [社区模板库](#社区模板库)
- [AI 驱动的工作流](#ai-驱动的工作流)
- [用例](#用例)
- [构建完整的跟踪设置](#构建完整的跟踪设置)
- [实施同意管理](#实施同意管理)
- [批量操作和重命名](#批量操作和重命名)
- [自定义变量和逻辑](#自定义变量和逻辑)
- [适用于代理机构](#适用于代理机构)
- [工作原理](#工作原理)
- [安全功能](#安全功能)
- [自我托管](#自我托管)
- [服务账户模式（S2S）](#服务账户模式s2s)
- [Docker 设置](#docker-设置)
- [Google Cloud 设置](#google-cloud-设置)
- [可用工具](#可用工具)
- [读取操作](#读取操作)
- [实用工具](#实用工具)
- [写入操作](#写入操作)
- [服务器端容器工具](#服务器端容器工具)
- [发布](#发布)
- [模板](#模板)
- [资源和提示](#资源和提示)
- [资源（基于 URI 的访问）](#资源基于-uri-的访问)
- [提示（工作流模板）](#提示工作流模板)
- [更好的 AI 上下文](#更好的-ai-上下文)
- [llms.txt - 适用于任何 LLM 或代理](#llmstxt-适用于任何-llm-或代理)
- [Claude 代码技能 - 引导式工作流](#claude-代码技能-引导式工作流)
- [GTM API 技能 - API 参考](#gtm-api-技能-api-参考)
- [架构](#架构)
- [已知问题](#已知问题)
- [链接](#链接)
- [作者](#作者)
- [许可证](#许可证)
---
## 支持的 AI 客户端
| 客户端 | 传输方式 | 认证流程 | 状态 |
|--------|-----------|-----------|--------|
| [Claude](https://claude.ai)（网页和桌面端） | 可流式 HTTP | OAuth 2.1 + PKCE | 支持 |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（CLI） | 可流式 HTTP | OAuth 2.1 + PKCE | 支持 |
| [ChatGPT](https://chatgpt.com) | 可流式 HTTP | OAuth 2.1 + PKCE | 支持 |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | 可流式 HTTP | OAuth 2.1 + PKCE（DCR） | 支持 |
| [Cursor](https://cursor.com) | 可流式 HTTP | OAuth 2.1 + PKCE | 支持 |
服务器是**客户端无关**的 - 任何支持使用 HTTP 传输的 OAuth 2.1 和 PKCE 的 MCP 客户端都应该开箱即用，包括使用动态客户端注册（RFC 7591）和不使用的客户端。
---
## 您可以做什么？
询问您的 AI 助手：
- *"列出我的所有 GTM 容器"*
- *"为表单提交创建一个 GA4 事件标签"*
- *"审核此容器的配置和重复项"*
- *"为营销团队生成跟踪计划文档"*
- *"设置电子商务购买跟踪"*
- *"发布我们刚刚进行的更改"*
无需再点击 GTM 界面。无需再复制粘贴配置。只需描述您需要的内容。
---
## 快速入门
### Claude（网页和桌面端）
**Claude.ai：**
1. 进入 **设置** → **连接器** → **添加自定义连接器**
2. 输入：`https://mcp.gtmeditor.com`
3. 点击 **添加** 并使用 Google 登录
**Claude Code（CLI）：**
```bash
claude mcp add -t http gtm https://mcp.gtmeditor.com
```
### ChatGPT
1. 进入 [OpenAI 应用平台](https://platform.openai.com/apps)
2. 添加具有 URL 的 MCP 集成：`https://mcp.gtmeditor.com`
3. 使用您的 Google 账户授权
### Gemini CLI
```bash
gemini mcp add --transport http --url https://mcp.gtmeditor.com gtm
```
### Cursor
1. 打开 **设置** > **MCP**
2. 点击 **添加新的 MCP 服务器**
3. 设置类型为 **URL** 并输入：`https://mcp.gtmeditor.com/authorize`
4. 使用您的 Google 账户授权
或添加到您的 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"gtm": {
"url": "https://mcp.gtmeditor.com/authorize"
}
}
}
```
---
## 功能
### 标签管理
创建和修改任何 GTM 标签类型：
- **GA4 配置和事件** - 使用正确的测量 ID 设置 Google Analytics 4
- **电子商务跟踪** - 购买、添加到购物车、查看商品事件
- **自定义 HTML** - 注入脚本、像素和自定义代码
- **自定义图像** - 使用缓存破坏的跟踪像素
### 触发器管理
为任何场景构建触发器：
- 页面浏览量（所有页面或特定 URL）
- 自定义 dataLayer 事件
- 点击跟踪
- 表单提交
- 基于定时器的触发器
- 用于复杂条件的触发器组
### 容器操作
- 浏览账户、容器和工作区
- 从工作区更改中创建版本
- 发布版本以生效
- 使用文件夹组织
- 启用/禁用内置变量
### 服务器端容器
完全支持服务器端 GTM 容器：
- **客户端** - 创建、更新和删除服务器端客户端（例如 GA4 客户端）
- **转换** - 使用允许、排除和增强规则控制事件参数
### 社区模板库
从 Google 的社区模板库导入模板：
- *"导入 iubenda Cookie 同意模板"*
- *"将 Cookiebot 添加到我的容器中"*
- *"使用库模板设置 Facebook Pixel"*
AI 将搜索模板、找到 GitHub 仓库并自动导入。
### AI 驱动的工作流
**容器审核**
*"审核我的容器的配置和重复项"* - 分析工作区是否存在：
- 命名不一致
- 重复标签
- 孤立触发器
- 安全问题
- 最佳实践违规
**跟踪计划生成**
*"生成跟踪计划"* - 创建以下内容的 Markdown 文档：
- 所有事件及其触发器
- 数据层需求
- 变量定义
- 实现说明
**GA4 设置建议**
*"帮助我为电子商务设置 GA4"* - 建议：
- 要创建的标签
- 触发器配置
- 所需变量
- 数据层实现代码
---
## 用例
### 构建完整的跟踪设置
要求 AI 从头开始创建完整的 GA4 电子商务实施：
- *"为我的商店设置 GA4 电子商务跟踪"*
- 创建 12+ 个标签（配置 + 所有电子商务事件）
- 为每个 dataLayer 事件创建匹配的触发器
- 为商品、货币、价值、transaction_id 创建数据层变量
- 遵循 Google 的推荐事件命名和参数
### 实施同意管理
将 OneTrust 等隐私工具与您的跟踪集成：
- *"仅在授予分析同意时触发 GA4"*
- 创建同意检查变量
- 设置条件触发器
- 更新现有标签以尊重用户选择
### 批量操作和重命名
大规模管理容器：
- *"为所有电子商务触发器添加 'ecom -' 前缀"*
- *"更新所有标签以使用测量 ID 变量"*
- 通过对话重命名、更新或组织数十个项目
### 自定义变量和逻辑
创建复杂跟踪逻辑：
- *"创建一个返回本地时间戳的变量"*
- *"在购买标签中添加自定义参数"*
- 自定义 JavaScript 变量、数据层映射等
### 适用于代理机构
- 管理多个客户端容器（演示中显示 7+ 账户）
- 跨客户端标准化实现
- 新项目快速设置
- 安全地版本化和发布更改
---
## 工作原理
GTM MCP 服务器使用 [Model Context Protocol](https://modelcontextprotocol.io) 将 AI 助手连接到 Google Tag Manager API。当您要求 Claude 或 ChatGPT 管理您的 GTM 时，它会：
1. **身份验证** 使用您的 Google 账户（OAuth 2.1）
2. **读取** 您的容器配置
3. **执行** 您请求的变化
4. **确认** 在进行破坏性操作之前
您的凭证永远不会被存储 - 服务器使用令牌式身份验证，您可以随时从 Google 账户撤销。
---
## 安全功能
- **删除和发布需要确认**
- **仅工作区更改** - 在您发布之前不会生效
- **版本控制** - 所有更改首先创建版本
- **审核日志** - 跟踪更改内容
---
## 自我托管
想运行您自己的实例？
### 服务账户模式（S2S）
自我托管部署可以使用 Google 服务账户，以便整个团队共享访问权限 - 无需个人 GTM 权限。
**工作原理：**
- 服务器使用服务账户身份验证到 Google Tag Manager
- 团队成员使用共享 API 密钥连接 - 无需个人 GTM 访问权限
- AI 客户端（Claude Code、ChatGPT 等）仍然会进行一次性的 OAuth 登录 **到服务器**，但所有 GTM 调用都在服务账户下运行
- 程序化客户端（脚本、CI/CD、API）完全跳过 OAuth，直接使用 API 密钥
**设置：
1. 在 [Google Cloud Console](https://console.cloud.google.com/) → IAM & Admin → 服务账户中创建服务账户
2. 在 [Google Tag Manager](https://tagmanager.google.com) → 账户 → 管理 → 用户管理 → 将服务账户电子邮件添加为 **账户管理员**
3. 下载 JSON 密钥文件
4. 配置服务器：
```bash
SERVICE_ACCOUNT_API_KEY=$(openssl rand -hex 32) # 与您的团队共享此密钥
GOOGLE_SERVICE_ACCOUNT_KEY_JSON=$(cat key.json) # 粘贴 JSON 内容
go run main.go
```
在 GCP（Cloud Run、GKE、Compute Engine）上：省略 `GOOGLE_SERVICE_ACCOUNT_KEY_JSON` - 自动使用工作负载身份。
**连接 Claude Code：
将 API 密钥添加为预配置的头部，以便 Claude Code 自动使用 S2S：
```json
{
"mcpServers": {
"gtm": {
"type": "http",
"url": "http://your-server:8080",
"headers": {
"Authorization": "Bearer your-api-key"
}
}
}
}
```
**程序化 / API 访问：
任何 HTTP 客户端都可以直接调用服务器 - 无需浏览器，无需 OAuth：
```bash
curl -H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
http://your-server:8080/mcp \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
参阅 [`examples/gtm_agent.py`](examples/gtm_agent.py) 以获取使用 Claude 通过 API 密钥以编程方式管理 GTM 的完整 Python 代理。
---
### Docker 设置
```bash
git clone https://github.com/paolobietolini/gtm-mcp-server.git
cd gtm-mcp-server
# 创建 .env 文件
cat > .env << 'EOF'
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
JWT_SECRET=$(openssl rand -base64 32)
BASE_URL=http://localhost:8080
EOF
# 启动服务器
docker compose up -d
# 添加到 Claude
claude mcp add -t http gtm http://localhost:8080
```
#### 反向代理（TRUST_PROXY）
在反向代理后面运行时（Caddy、nginx、Cloudflare），设置 `TRUST_PROXY=true`，以便速率限制器使用 `X-Forwarded-For` 中的客户端真实 IP 地址代替代理地址：
```bash
TRUST_PROXY=true
```
Docker Compose 设置会自动设置此参数，因为容器在 Caddy 后运行。当直接运行二进制文件而无需代理时，请将其设置为未设置或 `false` - 否则客户端可以伪造 IP 地址以绕过速率限制。
#### Docker-to-Docker
如果另一个容器需要通过内部 Docker 网络别名访问 MCP 服务器，请在您的 `.env` 中添加 `ALLOWED_HOSTS`：
```bash
ALLOWED_HOSTS=gtm-mcp:8080
```
这使得对受信任的内部主机名的动态 URL 解析，同时保持服务器对主机头注入攻击的安全性。
### Google Cloud 设置
1. 进入 [Google Cloud Console](https://console.cloud.google.com/)
2. 启用 **Tag Manager API**
3. 创建 **OAuth 2.0 凭证**（Web 应用程序）
4. 添加重定向 URI:
```
https://claude.ai/api/mcp/auth_callback
https://claude.com/api/mcp/auth_callback
https://chatgpt.com/connector_platform_oauth_redirect
https://your-domain.com/oauth/callback
```
---
## 可用工具
### 读取操作
| 工具 | 描述 |
|------|-------------|
| `list_accounts` | 列出所有 GTM 账户 |
| `list_containers` | 列出账户中的容器 |
| `list_workspaces` | 列出容器中的工作区 |
| `list_tags` | 列出工作区中的所有标签 |
| `get_tag` | 按 ID 获取标签详情 |
| `list_triggers` | 列出所有触发器 |
| `get_trigger` | 按 ID 获取触发器详情 |
| `list_variables` | 列出所有变量 |
| `get_variable` | 按 ID 获取变量详情 |
| `list_folders` | 列出工作区中的文件夹 |
| `get_folder_entities` | 获取文件夹中的标签/触发器/变量 |
| `list_built_in_variables` | 列出工作区中启用的内置变量 |
### 实用工具
| 工具 | 描述 |
|------|-------------|
| `ping` | 测试服务器连接性 |
| `auth_status` | 检查身份验证状态 |
### 写入操作
| 工具 | 描述 |
|------|-------------|
| `update_account` | 重命名 GTM 账户 |
| `create_container` | 在账户中创建新容器 |
| `update_container` | 重命名容器（保留用法上下文、域、备注） |
| `delete_container` | 删除容器（需要确认） |
| `create_workspace` | 在容器中创建新工作区 |
| `create_tag` | 创建新标签 |
| `update_tag` | 修改现有标签 |
| `delete_tag` | 删除标签（需要确认） |
| `create_trigger` | 创建新触发器 |
| `update_trigger` | 修改现有触发器 |
| `delete_trigger` | 删除触发器（需要确认） |
| `create_variable` | 创建新变量 |
| `update_variable` | 修改现有变量 |
| `delete_variable` | 删除变量（需要确认） |
| `enable_built_in_variables` | 在工作区中启用内置变量类型 |
| `disable_built_in_variables` | 禁用内置变量类型（需要确认） |
### 服务器端容器工具
| 工具 | 描述 |
|------|-------------|
| `list_clients` | 列出工作区中的所有客户端 |
| `get_client` | 按 ID 获取客户端详情 |
| `create_client` | 创建新客户端 |
| `update_client` | 修改现有客户端 |
| `delete_client` | 删除客户端（需要确认） |
| `list_transformations` | 列出工作区中的所有转换 |
| `get_transformation` | 按 ID 获取转换详情 |
| `create_transformation` | 创建新转换 |
| `update_transformation` | 修改现有转换 |
| `delete_transformation` | 删除转换（需要确认） |
### 发布
| 工具 | 描述 |
|------|-------------|
| `get_workspace_status` | 在版本化之前检查待处理更改和合并冲突 |
| `list_versions` | 列出所有容器的版本，包含标签/触发器/变量计数 |
| `create_version` | 从工作区更改中创建版本 |
| `publish_version` | 发布版本（需要确认） |
### 模板
| 工具 | 描述 |
|------|-------------|
| `get_tag_templates` | 获取 GA4/HTML 标签参数示例 |
| `get_trigger_templates` | 获取触发器配置示例 |
| `list_templates` | 列出工作区中的自定义模板 |
| `get_template` | 获取模板详情，包括模板代码 |
| `create_template` | 从 .tpl 代码创建自定义模板 |
| `update_template` | 修改现有模板 |
| `delete_template` | 删除模板（需要确认） |
| `import_gallery_template` | 从社区画廊导入模板 |
---
## 资源和提示
### 资源（基于 URI 的访问）
通过结构化 URI 访问 GTM 数据：
```
gtm://accounts
gtm://accounts/{id}/containers
gtm://accounts/{id}/containers/{id}/workspaces
gtm://accounts/.../workspaces/{id}/tags
gtm://accounts/.../workspaces/{id}/triggers
gtm://accounts/.../workspaces/{id}/variables
```
最佳实践文档（静态 Markdown，无需身份验证）：
```
gtm://best-practices # 所有规则文档索引
gtm://best-practices/naming-organization # 命名约定、文件夹、孤立清理
gtm://best-practices/safe-edit-workflow # 工作区 → 差异 → 版本 → 发布
gtm://best-practices/ga4-consent # GA4 模式、同意模式 v2
gtm://best-practices/server-side # 客户端、转换、PII、第一方域
```
## 更好的 AI 上下文
### llms.txt - 适用于任何 LLM 或代理
### Claude 代码技能 - 引导式工作流
### GTM API 技能 - API 参考
### 提示 (工作流程模板)
| 提示 | 描述 |
|--------|-------------|
| `audit_container` | 对内置最佳实践进行全面容器分析 |
| `best_practices_review` | 按类别评分的审查（通过/警告/失败），并提供具体修复建议 |
| `plan_safe_edit` | 按照安全编辑工作流程逐步更改的计划 |
| `generate_tracking_plan` | Markdown 文档生成器 |
| `suggest_ga4_setup` | GA4 实现建议 |
| `find_gallery_template` | 查找和导入社区画廊模板的指南 |
---
## 更好的 AI 上下文
服务器提供了两种资源，以帮助 AI 助手更有效地使用它 — 一种适用于任何 LLM 或代理，另一种专门适用于 Claude Code 用户。它还附带了 MCP 资源（`gtm://best-practices`）的特定 GTM 配置规则，因此任何连接的代理都可以读取它们后再进行更改。
### llms.txt — 适用于任何 LLM 或代理
服务器在其根目录中托管一个 [`llms.txt`](https://mcp.gtmeditor.com/llms.txt) 文件，任何 LLM 或代理都可以获取它以获取上下文。它记录了 GTM 层次结构、所有可用的工具、常见工作流程、安全规则和 GA4 参数格式。
```
https://mcp.gtmeditor.com/llms.txt
```
此文件遵循 [llms.txt](https://llmstxt.org/) 标准。支持 llms.txt 的代理框架将自动获取此文件。您也可以手动获取它或将其作为系统提示包含在自定义集成中。
### Claude Code 技能 — 有指导的工作流程
对于 Claude Code 用户，请安装 **GTM MCP 技能** 以获取有指导的工作流程、要避免的反模式和逐步任务模式：
```bash
# 一行安装
curl -sL https://github.com/paolobietolini/gtm-mcp-server/archive/main.tar.gz | tar xz && \
mkdir -p ~/.claude/skills && \
cp -r gtm-mcp-server-main/skills/gtm-mcp ~/.claude/skills/ && \
rm -rf gtm-mcp-server-main
```
或克隆和复制：
```bash
git clone https://github.com/paolobietolini/gtm-mcp-server.git
cp -r gtm-mcp-server/skills/gtm-mcp ~/.claude/skills/
```
该技能教导 Claude 如何发现 ID、创建具有正确参数格式的标签、遵循发布工作流程并避免常见错误。
### GTM API 技能 — API 参考
对于更深入的 API 上下文（参数模式、验证规则、所有实体类型的请求模板），请安装 **GTM API 技能**：
**Claude Code：**
```bash
curl -sL https://github.com/paolobietolini/gtm-api-for-llms/archive/main.tar.gz | tar xz && \
mkdir -p ~/.claude/skills && \
cp -r gtm-api-for-llms-main/skills/gtm-api ~/.claude/skills/ && \
rm -rf gtm-api-for-llms-main
```
**OpenAI Codex：**
```bash
curl -sL https://github.com/paolobietolini/gtm-api-for-llms/archive/main.tar.gz | tar xz && \
mkdir -p ~/.codex/skills && \
cp -r gtm-api-for-llms-main/skills/gtm-api ~/.codex/skills/ && \
rm -rf gtm-api-for-llms-main
```
[GTM API for LLMs](https://github.com/paolobietolini/gtm-api-for-llms) 仓库提供了 LLM 优化的文档：请求模板、验证规则、工作流程算法和所有 GTM 实体类型的完整模式，包括服务器端容器。
---
## 架构
- **协议：** 模型上下文协议（MCP）通过 HTTP
- **身份验证：** OAuth 2.1 with PKCE
- **标准：** RFC 8414, RFC 7591, RFC 9728
---
## 已知问题
### 🐛 `autoEventFilter` 被 Google Tag Manager API 静默丢弃
通过 API 创建或更新 `linkClick`、`click` 或 `formSubmission` 触发器时，用于 “某些链接点击”/“某些表单提交” 条件 的 `autoEventFilter` 字段被 Google Tag Manager API 静默丢弃。API 返回 `200 OK` 及新的指纹，但不保留 `autoEventFilter`。
通过 HTTP 级别的调试已确认这一点：正确的 JSON 在请求体中发送，但 Google 的响应中省略了该字段。而 `filter` 和 `customEventFilter` 字段则正常工作。
**解决方法：** 通过 [GTM 网页界面](https://tagmanager.google.com) 手动配置 `autoEventFilter` 条件。MCP 服务器可以通过 UI 读取已设置 `autoEventFilter` 的触发器。
**状态：** [#33](https://github.com/paolobietolini/gtm-mcp-server/issues/33)
---
## 链接
- [GitHub 仓库](https://github.com/paolobietolini/gtm-mcp-server)
- [GTM API 参考](https://github.com/paolobietolini/gtm-api-for-llms)
- [MCP 规范](https://modelcontextprotocol.io)
---
## 作者
**Paolo Bietolini**
mcp@paolobietolini.com
---
## 许可证
[BSD-3-Clause](LICENSE)
连接信息
猜你喜欢
暂无推荐服务器