shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

gtm-mcp

一个用于Claude的Google Tag Manager MCP服务器，提供GTM账户、容器、标签、触发器和变量的管理功能，支持容器版本发布和完整的工作区管理。

article

README

🚀 GTM MCP Server

GTM MCP Server 是一个模型上下文协议（MCP）服务器，它能让 Claude 与 Google Tag Manager 进行交互，可实现对 GTM 账户、容器、标签、触发器和变量的管理等功能。

🚀 快速开始

前提条件

  • Python 3.10 或更高版本
  • Claude Desktop（或任何与 MCP 兼容的客户端，如 Cursor）
  • 拥有访问 Google Tag Manager 的 Google 账户

✨ 主要特性

  • 列出 GTM 账户和容器
  • 管理标签、触发器和变量
  • 创建并发布容器版本
  • 完整的工作区管理

📦 安装指南

第 1 部分：安装软件包

pip install gtm-mcp

查看 PyPi

第 2 部分：创建 Google Cloud OAuth 凭证

步骤 1：创建 Google Cloud 项目

  1. 访问 Google Cloud 控制台
  2. 点击项目下拉菜单（左上角）
  3. 点击 “新建项目”
  4. 输入项目名称（例如：“My GTM MCP Server”）
  5. 点击 “创建”
  6. 等待项目创建完成并选择该项目

步骤 2：启用 Tag Manager API

  1. 在项目中，进入 “API 和服务” → “库”
  2. 搜索 “Tag Manager API”
  3. 点击它并点击 “启用”
  4. 等待其启用（可能需要一分钟）

步骤 3：配置 OAuth 同意屏幕

  1. 进入 “API 和服务” → “OAuth 同意屏幕”
  2. 选择 “外部”（除非你有 Google Workspace）
  3. 点击 “创建”
  4. 填写必填字段：
    • 应用名称：My GTM MCP（或你喜欢的任何名称）
    • 用户支持电子邮件：你的电子邮件
    • 开发者联系电子邮件：你的电子邮件
  5. 点击 “保存并继续”
  6. 点击 “更新” 然后 “保存并继续”
  7. 将你的电子邮件添加为 测试用户
  8. 点击 “保存并继续”

步骤 4：创建 OAuth 凭证

  1. 进入 “API 和服务” → “凭证”
  2. 点击 “创建凭证” → “OAuth 客户端 ID”
  3. 选择 “桌面应用” 作为应用类型
  4. 输入名称：“GTM MCP Desktop Client”
  5. 点击 “创建”
  6. 重要提示：会弹出一个显示凭证的对话框 - 暂时不要关闭它

步骤 5：保存你的凭证

从弹出的对话框中：

  1. 复制 客户端 ID（格式类似：123456789-abc123.apps.googleusercontent.com）
  2. 复制 客户端密钥（格式类似：GOCSPX-...）
  3. 从 Google Cloud 控制台的顶部栏（项目名称旁边）记录你的 项目 ID
  4. 将这些信息保存在安全的地方 - 你将在下一步中用到它们

你也可以下载 JSON 文件，但你只需要上述三个值。

第 3 部分：配置 Claude Desktop

编辑你的 Claude Desktop 配置文件：

  • Linux：~/.config/Claude/claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Claude Code：~/.claude.json

添加你的凭证：

{
  "mcpServers": {
    "gtm-mcp": {
      "command": "gtm-mcp",
      "env": {
        "GTM_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GTM_CLIENT_SECRET": "GOCSPX-your-client-secret",
        "GTM_PROJECT_ID": "your-project-id"
      }
    }
  }
}

替换这些值 为你在第 2 部分步骤 5 中的实际凭证。

注意：如果你已经配置了其他 MCP 服务器，只需将 "gtm-mcp" 条目添加到现有的 "mcpServers" 对象中。

第 4 部分：重启并授权

  1. 完全重启 Claude Desktop（关闭并重新打开）

  2. 让 Claude 使用 GTM 工具（例如：“列出我的 GTM 账户”）

  3. 首次授权 - 浏览器窗口将自动打开：

    • 使用你的 Google 账户登录
    • 你会看到 “Google 尚未验证此应用” 警告
    • 点击 “高级” → “转到 [你的应用名称]（不安全）”
    • 这是安全的，因为 你自己创建了该应用
    • 授予请求的权限
    • 你会看到 “认证流程已完成”
    • 返回 Claude Desktop

  4. 你的授权信息将本地保存 - 你无需再次进行此操作！

💻 使用示例

基础用法

在配置完成后，你可以让 Claude 使用 GTM 工具，例如询问 “List my GTM accounts” 来列出你的 GTM 账户。

高级用法

可以通过组合不同的 GTM 工具命令，实现更复杂的操作，例如先列出账户，再列出特定账户下的容器等。

📚 详细文档

可用工具

配置完成后，Claude 可以使用以下 GTM 工具： | 工具 | 描述 | |------|-------------| | gtm_list_accounts | 列出所有你的 GTM 账户 | | gtm_list_containers | 列出账户中的容器 | | gtm_list_tags | 列出工作区中的标签 | | gtm_get_tag | 获取特定标签的详细配置 | | gtm_create_tag | 创建新标签 | | gtm_update_tag | 更新现有标签 | | gtm_list_triggers | 列出工作区中的触发器 | | gtm_create_trigger | 创建新触发器 | | gtm_list_variables | 列出工作区中的变量 | | gtm_create_variable | 创建新变量（常量、数据层、cookie、URL 等） | | gtm_publish_container | 创建并发布新的容器版本 |

认证工作原理

此 MCP 服务器使用 OAuth 2.0 安全地访问 Google Tag Manager：

  1. 你在自己的 Google Cloud 项目中创建 OAuth 凭证
  2. 你在 Claude Desktop 中配置这些凭证
  3. 首次使用：浏览器将打开以授权访问你的 GTM 账户
  4. 你的令牌 将本地保存在你的机器上（~/.gtm-mcp-token.json），以供将来使用

为什么我需要自己的 OAuth 凭证？

出于安全和隐私考虑：

  • ✅ 你完全控制 OAuth 应用
  • ✅ 用户之间没有共享凭证
  • ✅ 你可以随时撤销访问权限
  • ✅ 你的凭证保持私密
  • ✅ 符合 Google 的 OAuth 政策

升级

运行 pip install --upgrade gtm-mcp

故障排除

"Missing required OAuth credentials" 错误

问题：MCP 服务器找不到你的凭证。 解决方案：确保你：

  • 在 claude_desktop_config.json（或 ~/.claude.json）中正确设置环境变量
  • 编辑配置后重启了 Claude Desktop
  • 使用了正确的格式（JSON 中没有额外的引号）
  • 配置文件是有效的 JSON（如果不确定，可以使用 JSON 验证器）

"Google hasn't verified this app" 警告

问题：首次授权期间 Google 显示安全警告。 解决方案：对于个人 OAuth 应用，这是 完全正常的。因为你自己创建了 OAuth 应用，所以 Google 会显示此警告。 要继续操作：点击 “高级” → “转到 [应用名称]（不安全）” 这是安全的，因为 你控制该应用。

无法访问 GTM 账户

可能原因：

  • 你的 Google 账户没有访问任何 GTM 账户的权限
  • 你在授权期间没有授予所有请求的权限
  • 你的 Google Cloud 项目中未启用 Tag Manager API

解决方案：

  1. 验证你的 Google 账户具有 GTM 访问权限
  2. 通过删除 ~/.gtm-mcp-token.json 并再次尝试重新授权
  3. 检查 Google Cloud 控制台中是否启用了 Tag Manager API

连接问题

调试步骤：

  1. 验证 Claude Desktop 已完全重启
  2. 检查 Claude Desktop 日志中是否有 MCP 服务器错误
  3. 验证 gtm-mcp 命令是否有效：在终端中运行 gtm-mcp
  4. 检查你的配置文件是否为有效的 JSON
  5. 确保所有三个环境变量都正确设置

安装后找不到软件包

问题：安装后找不到 gtm-mcp 命令。 解决方案：

# 确保 pip 安装位置在 PATH 中
pip install --user gtm-mcp

# 或者使用 pipx 进行隔离安装
pipx install gtm-mcp

撤销访问权限

要撤销对 GTM 账户的访问权限：

  1. 访问 Google 账户权限
  2. 在列表中找到你的应用名称
  3. 点击 “移除访问权限”
  4. 删除本地令牌文件：rm ~/.gtm-mcp-token.json

你可以随时通过在 Claude 中再次使用任何 GTM 工具重新授权。

安全注意事项

  • 你的 OAuth 凭证仅属于你 - 请保持私密
  • 切勿共享你的客户端密钥 - 将其视为密码
  • 你的访问令牌存储在本地：~/.gtm-mcp-token.json
  • 你可以随时在 Google Cloud 控制台中重新生成凭证
  • 你可以随时从 Google 账户设置中撤销访问权限
  • 此服务器仅访问 GTM - 不访问其他 Google 服务

开发

运行测试

pip install -e ".[dev]"
pytest

📄 许可证

详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献代码！请按以下步骤操作：

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 提交拉取请求

对于错误报告和功能请求，请 创建一个问题。

🆘 获取帮助

如果你遇到问题：

  1. 查看上面的 故障排除 部分
  2. 查看 Claude Desktop 日志中的错误消息
  3. 验证你的 Google Cloud 项目是否启用了 Tag Manager API
  4. 确保配置中的环境变量设置正确
  5. 在 GitHub 上 创建一个问题，并提供以下信息：
    • 你的操作系统
    • Python 版本（python --version）
    • Claude Desktop 日志中的错误消息
    • 重现问题的步骤
help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client