Gtm MCP

🚀 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 工具：

認證工作原理

此 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 日誌中的錯誤消息
   • 重現問題的步驟