内容
# 标签管理器MCP
谷歌标签管理器的MCP（模型上下文协议）服务器。
询问您的AI助手关于您的GTM设置 — 账户、容器、标签、触发器、变量、未发布的更改 — 并让它编辑工作区草稿：创建、更新和删除标签、触发器和变量，然后版本化和发布容器。从Claude Code、Claude Desktop或任何MCP客户端均可操作。
## 为什么选择这个？
- **一次性身份验证 — 无需重复身份验证。** 身份验证使用您自己的OAuth客户端的纯谷歌应用程序默认凭证（ADC）；刷新令牌不会过期，因此您只需登录一次即可忘记。无需托管的OAuth会话，该会话每隔几天就会过期并要求进行另一次浏览器点击。
- **无需服务账户。** 服务器以*您*的身份运行，使用您的谷歌账户已经拥有的GTM权限。无需创建服务账户JSON密钥、授予容器访问权限、轮换或意外提交。
- **本地和直接。** 在您的机器上通过stdio运行；您的GTM数据直接在您和`tagmanager.googleapis.com`之间流动。中间没有第三方代理。
- **为LLM上下文窗口而设计。** GTM的原始标签JSON非常庞大（单个GA4事件标签很容易就有数百行）。`list_*`工具返回精简的骨架；`get_*`工具仅在需要时获取完整详细信息。
- **设计时考虑配额。** GTM API每个项目每100秒仅允许25个请求。服务器重试速率限制（429/403）和服务器错误，呈指数级退避，并在第一次命中后自我限制。错误以可操作的错误信息返回，而不是原始堆栈跟踪。
## 工具
**读取**
| 工具 | 用途 |
|---|---|
| `list_accounts` | 您可以访问的GTM账户（可选谷歌标签账户） |
| `list_containers` | 账户中的容器 |
| `list_workspaces` | 容器中的工作区 |
| `get_workspace_status` | 未发布的更改和合并冲突 |
| `list_tags` / `get_tag` | 标签 — 精简列表 / 完整配置 |
| `list_triggers` / `get_trigger` | 触发器 — 精简列表 / 完整配置 |
| `list_variables` / `get_variable` | 变量 — 精简列表 / 完整配置 |
**写入**
| 工具 | 用途 |
|---|---|
| `create_tag` / `create_trigger` / `create_variable` | 在工作区草稿中创建实体 |
| `update_tag` / `update_trigger` / `update_variable` | 合并部分更改到实体中 |
| `delete_tag` / `delete_trigger` / `delete_variable` | 删除实体（需要`confirm=true`） |
**发布**
| 工具 | 用途 |
|---|---|
| `list_versions` | 容器版本头 — 精简列表 |
| `get_version` / `get_live_version` | 一个版本 / 当前实时版本，内容精简 |
| `create_version` | 将工作区快照到版本（消耗工作区；返回`newWorkspacePath`） |
| `publish_version` | 发布版本到实时环境（需要`confirm=true`） |
写入安全模型：
- **编辑和上线是分开的。** 创建/更新/删除只会触及工作区草稿；只有`publish_version`会更改实时网站的内容，并且需要`confirm=true`。您可以在上线前在GTM UI中（或通过`get_workspace_status` / `get_live_version`）查看更改。
- **更新是合并补丁。** 模型只会发送要更改的字段；服务器会重新读取实体并提交其`fingerprint`，因此并发编辑会干净地失败而不是被覆盖。
- **删除和发布需要显式确认** （`confirm=true`）并且会声明为`destructiveHint`。`create_version`也是破坏性的（它会消耗工作区），但不会在`confirm`上设门槛。
- **写入时不会盲目重试。** 速率限制拒绝会重试（它们在执行前发生）；不明确的5xx错误不会重试，因此创建永远不会被静默重复。
## 先决条件
- Python >= 3.10
- [pipx](https://pipx.pypa.io/stable/installation/)
- [gcloud CLI](https://cloud.google.com/sdk/docs/install)
- 具有访问您的GTM容器的谷歌账户
- 您可以启用API的任意GCP项目（仅用于配额归属）
## 设置
**1. 安装**
```bash
pipx install tagmanager-mcp
```
**2. 在您的配额项目上启用标签管理器API**
```bash
gcloud services enable tagmanager.googleapis.com --project=YOUR_PROJECT
```
**3. 创建桌面OAuth客户端**
谷歌阻止了用于标签管理器作用域的gcloud内置OAuth客户端（“此应用被阻止”），因此您需要使用自己的：
- GCP控制台 → **谷歌身份验证平台 → 客户端 → 创建客户端** → 应用程序类型 **桌面应用程序** → 创建，然后下载JSON。
- 在**受众**页面上，将应用程序发布到**生产环境**。如果应用程序处于测试状态，则发布的刷新令牌将在7天后过期 — 这正是该项目旨在避免的重复身份验证。
**4. 登录**
```bash
gcloud auth application-default login \
--client-id-file=path/to/your-client.json \
--scopes=https://www.googleapis.com/auth/tagmanager.readonly,https://www.googleapis.com/auth/tagmanager.edit.containers,https://www.googleapis.com/auth/tagmanager.edit.containerversions,https://www.googleapis.com/auth/tagmanager.publish,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project YOUR_PROJECT
```
作用域是根据每个层级的需求累加的：删除`tagmanager.publish` + `tagmanager.edit.containerversions`以进行仅编辑（无发布），或删除`tagmanager.edit.containers`以进行仅读取设置。超出您授予的作用域的工具会以清晰的重新登录提示失败，而其他一切保持正常运行。
浏览器会警告“谷歌尚未验证此应用” — 它是您自己的应用；选择高级 → 继续。
## 连接MCP客户端
**Claude Code** 从您的shell启动并继承其PATH，因此直接命令即可：
```bash
claude mcp add gtm -- tagmanager-mcp
```
**Claude Desktop** （`claude_desktop_config.json`）由操作系统启动，**不**继承您的shell PATH，因此请为其提供绝对路径。使用`which tagmanager-mcp`打印：
```json
{
"mcpServers": {
"gtm": {
"command": "/Users/you/.local/bin/tagmanager-mcp"
}
}
}
```
## 示例提示
- “我有哪些GTM账户和容器？”
- “GTM-XXXXXXX容器的默认工作区中有多少个标签，按类型分组？”
- “哪些标签已暂停？”
- “显示我购买标签的完整配置以及触发它的触发器。”
- “当前工作区是否有未发布的更改？有什么变化？”
- “查找没有标签引用的触发器。”
- “暂停所有在结账触发器上触发的标签。”
- “为`sign_up`创建自定义事件触发器，并为其触发创建一个GA4事件标签。”
## 配额
GTM API受到严格限制：**每天10,000个请求** 和 **每个GCP项目每100秒0.25 QPS（25个请求）** — 用户配额覆盖不会提高它。普通的审计对话可以舒适地适应；避免一次跨多个容器进行“每个容器中的每个标签”的扫描。
## 故障排除
- **登录时“此应用被阻止”** — 您使用了gcloud的默认OAuth客户端；请使用`--client-id-file`传递您自己的（设置步骤3）。
- **403提到权限不足** — 您的ADC早于此设置；请重新运行设置步骤4中的登录命令。
- **错误提到启用API / 配额项目** — 运行设置步骤2和`set-quota-project`；错误消息本身带有确切的命令。
## 开发
```bash
git clone https://github.com/jinchliu/tagmanager-mcp && cd tagmanager-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/nox -s tests # 标准库单元测试，完全离线
.venv/bin/nox -s lint # black --check
.venv/bin/mcp dev tagmanager_mcp/server.py # MCP检查
```
将您的MCP客户端指向`.venv/bin/tagmanager-mcp`以运行检出而不是安装的版本。
