Public Google Ads MCP

谷歌广告MCP服务器

一个MCP（模型上下文协议）服务器，允许Claude/Copilot对Google Ads帐户数据进行只读访问。支持通过为每个请求传递客户ID来查询任何客户帐户。

它的作用

显示31个工具。报告工具需要 customer_id 参数加可选 date_range_days 或 date_from/date_to 输入，许多还支持 活动/广告组过滤器和状态过滤器。帐户发现从开始 get_accessible_accounts.

面向营销人员的非技术概述：参见 docs/MEDIA_TEAM_GUIDE.md --简明的语言“我能问克劳德什么？”指南，并附有具体的提示示例，按用例分组。

______________________________________________________________________

快速入门--安装依赖项

cd google-ads-mcp
uv sync

______________________________________________________________________

设置-Google Ads API凭据

1. 复制 .env.example 到 .env
2. 填写您的Google Ads API证书(安装指南)

cp .env.example .env
# Edit .env with your credentials

所需的环境变量：

• GOOGLE_ADS_DEVELOPER_TOKEN -您的API开发者令牌
• GOOGLE_ADS_CLIENT_ID --OAuth2客户端ID
• GOOGLE_ADS_CLIENT_SECRET --OAuth2客户端机密
• GOOGLE_ADS_LOGIN_CUSTOMER_ID --您的MCC/经理帐户ID（无破折号）
• GOOGLE_ADS_REFRESH_TOKEN --OAuth2刷新令牌（使用 auth/generate_refresh_token.py 生成）

目标 customer_id 是 不 在 .env --它由代理根据请求传递。

生成刷新令牌

在预期的设置流程中，管理员向用户提供所有凭据，除了 GOOGLE_ADS_REFRESH_TOKEN.

如果你没有 GOOGLE_ADS_REFRESH_TOKEN 但是，运行：

powershell -ExecutionPolicy Bypass -File .\scripts\generate-refresh-token-windows.ps1

该脚本内容如下 GOOGLE_ADS_CLIENT_ID 和 GOOGLE_ADS_CLIENT_SECRET 从 .env，启动浏览器身份验证流，并打印刷新令牌供用户粘贴回 .env.

这假设OAuth应用程序已经由管理员准备好了。

如果你想直接使用低级助手，请运行：

uv run auth/generate_refresh_token.py -c client_secret.json

看 auth/README.md 对于全流量。

______________________________________________________________________

Windows上的Claude桌面（本机）

此项目不需要WSL。Claude Desktop可以直接在Windows上运行服务器。

有关截图的详细分步指南，请参阅 docs/WINDOWS_CLAUDE_DESKTOP_SETUP.md.

最快选项

如果你克隆了仓库，运行：

powershell -ExecutionPolicy Bypass -File .\scripts\setup-windows-claude-desktop.ps1

或者直接从互联网运行（不需要克隆）：

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/VidenGlobe/public-google-ads-mcp/main/scripts/setup-windows-claude-desktop.ps1 | iex"

该脚本安装缺少的工具，创建 .env，运行 uv sync，以及更新 claude_desktop_config.json 自动。

手动设置

第一步：安装Git和uv

打开 PowerShell 并运行：

winget install --id Git.Git -e
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后重新启动终端。

如果 winget 不可用，请从安装Git https://git-scm.com/download/win 紫外线来自 https://docs.astral.sh/uv/getting-started/installation/.

替代方案：安装带翼片的紫外线灯（不推荐）：

winget install --id astral-sh.uv -e

步骤2：克隆仓库并安装依赖项

cd $HOME
git clone https://github.com/VidenGlobe/public-google-ads-mcp google-ads-mcp
cd $HOME\google-ads-mcp
Copy-Item .env.example .env
notepad .env

编辑 .env 并填写您的Google Ads API证书：

• GOOGLE_ADS_DEVELOPER_TOKEN
• GOOGLE_ADS_CLIENT_ID
• GOOGLE_ADS_CLIENT_SECRET
• GOOGLE_ADS_LOGIN_CUSTOMER_ID

离开 GOOGLE_ADS_REFRESH_TOKEN 暂时空着。

步骤3：生成刷新令牌

cd $HOME\google-ads-mcp
powershell -ExecutionPolicy Bypass -File .\scripts\generate-refresh-token-windows.ps1

您的浏览器将打开。使用您的Google帐户登录并授权。刷新令牌将保存到 .env 自动。

步骤4：找到完整的路径 uv

运行：

where.exe uv

复制第一个结果。它通常看起来像：

C:\Users\\AppData\Local\Microsoft\WinGet\Links\uv.exe
OR
C:\Users\\.local\bin\uv.exe

步骤5：打开Claude Desktop配置文件

按 Win+R，粘贴此路径，然后按Enter键：

%APPDATA%\Claude\claude_desktop_config.json

如果文件不存在，请创建它。如果 Claude 文件夹不存在，请在以下位置创建 C:\Users\\AppData\Roaming\Claude\.

步骤6：添加MCP服务器配置

将此添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "C:/Users//.local/bin/uv.exe",
      "args": [
        "--directory",
        "C:/Users//google-ads-mcp",
        "run",
        "google-ads-mcp"
      ]
    }
  }
}

替换：

• C:/Users//.local/bin/uv.exe 确切的结果来自 where.exe uv （使用正斜杠 /)
• C:/Users//google-ads-mcp 使用克隆此仓库的文件夹（使用正斜杠）

步骤7：重新启动克劳德桌面

完全退出Claude Desktop（系统托盘→ 右击→ 退出），然后重新打开。

步骤8：验证

您应该在聊天输入区域看到一个工具图标。点击此处查看谷歌广告工具。尝试：

显示客户1234567890的所有活动

故障排除（Windows）

有关截图的详细分步指南，请参阅 docs/WINDOWS_CLAUDE_DESKTOP_SETUP.md.

______________________________________________________________________

Linux/macOS上的Claude桌面（本机）

添加 ~/.config/Claude/claude_desktop_config.json （Linux）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/google-ads-mcp", "run", "google-ads-mcp"]
    }
  }
}

备注：替换 /path/to/google-ads-mcp 带有项目目录的实际路径。

重新启动克劳德桌面。您将看到工具图标(🔧) 出现。

______________________________________________________________________

VS代码+GitHub副本（一步一步）

步骤1：创建MCP配置文件

复制示例配置：

cp .vscode/mcp.json.example .vscode/mcp.json

文件 .vscode/mcp.json 应包含：

{
  "servers": {
    "google-ads": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "google-ads-mcp"
      ]
    }
  },
  "inputs": []
}

步骤2：在VS代码设置中启用MCP支持

打开VS代码设置(Ctrl+,)并确保此设置已启用：

Chat > MCP: Enabled  →  ✅ checked

或添加到您的 settings.json:

{
  "chat.mcp.enabled": true
}

步骤3：在VS Code中启动MCP服务器

1. 打开 命令面板 (Ctrl+Shift+P)
2. 类型 MCP: List Servers 然后按Enter键
3. 你应该看看 google-ads 在列表中
4. 如果它显示为 停止，单击它并选择 “启动服务器”

或者：

1. 打开 命令面板 (Ctrl+Shift+P)
2. 类型 MCP: Start Server 然后按Enter键
3. 选择 google-ads 从下拉列表中

步骤4：验证它是否正在运行

1. 打开 副驾驶聊天 (Ctrl+Alt+I 或点击侧边栏中的复制图标）
2. 切换至 代理模式 （点击聊天面板顶部的下拉菜单——从“询问”或“编辑”切换到 “代理人”)
3. 你应该看到一个 🔧 工具图标 在聊天输入区域中--单击它以查看列出的31个Google Ads工具
4. 如果看不到工具图标，则服务器可能未启动——请返回步骤3

第五步：测试

在副驾驶聊天（代理模式）中，键入：

显示客户1234567890的所有活动

副驾驶将请求允许拨打电话 get_campaigns_report 工具。点击 “允许” 您将看到来自Google Ads API的实时数据。

故障排除

______________________________________________________________________

示例提示

连接后，在Copilot Chat（代理模式）或Claude中尝试以下操作：

• *“显示客户1234567890的所有活动”*
• *“在过去30天内对客户1234567890运行CPA诊断”*
• *“在客户1234567890的搜索词中查找浪费的支出”*
• *“对于客户1234567890，哪些关键字的质量得分低于5？”*
• *“显示客户1234567890的地理业绩”*
• *“比较客户1234567890在不同活动中的设备性能”*
• *“显示客户1234567890的人口统计细分（年龄+性别）”*
• *“哪些观众对客户表现最好1234567890？”*

______________________________________________________________________

远程部署——使用Google OAuth进行云运行

该服务器还作为远程HTTP MCP端点运行，因此Claude.ai的web连接器（以及通过OAuth的Claude Desktop/Code）可以使用它，而无需每个用户在本地安装。身份通过Google OAuth进行验证，授权通过电子邮件允许列表进行访问，Google Ads API访问权限保留在服务器端服务帐户（ADC）上。

环境变量（HTTP传输）

在Cloud Run服务上设置——这些由以下部分组成 部署/部署.sh示例 并通过 --set-env-vars:

GCP OAuth客户端设置

在GCP项目中创建一个Web类型的OAuth客户端，并注册这些重定向URI：

OAuth同意屏幕上的范围： openid, email 仅限（无敏感范围→ 无需谷歌验证）。将同意屏幕保持在测试模式，并将每个授权用户的电子邮件添加到测试用户列表中。

截至2026年3月，ChatGPT的自定义连接器使用动态的每个连接器回调URL，这与谷歌的精确匹配Web类型客户端重定向策略不兼容。ChatGPT支持目前还没有连接起来——它需要在谷歌前面有一个支持DCR的授权层（例如WorkOS AuthKit）。

部署

模板位于 部署/:

• 部署/部署.sh示例 — gcloud run deploy 具有资源/并发/超时设置和内联env-var组合的命令(${...})
• deploy/deploy-env.yaml.示例 --可选的env-var参考模板（默认脚本不使用）

复制 部署/部署.sh示例 到 deploy/deploy.sh，填写您的项目ID/编号/客户ID/允许的电子邮件，然后运行 ./deploy/deploy.sh.当地 deploy/deploy.sh 副本是合法的。

客户端设置

Claude.ai网站：设置→ 连接器→ 添加自定义连接器→ paste https:// （只有域——Claude.ai去掉了尾随斜线），在“高级”下，还有管理员提供的OAuth客户端ID+密钥。在提示时完成谷歌同意流程。

克劳德桌面版 （通过 mcp-remote)：添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\":\"\",\"client_secret\":\"\"}"
      ]
    }
  }
}

可观测性

每次工具调用都会向Cloud Logging发出结构化日志行：

tool_call tool=get_accessible_accounts user=alice@example.com args=customer_id
tool_done tool=get_accessible_accounts user=alice@example.com args=customer_id duration_ms=418

args=… 列出参数 *名字* 只有（值从不记录——没有PII泄漏）。这 user 字段从经过身份验证的呼叫者的谷歌电子邮件中解析； - 在stdio模式下。

查询最近的活动：

gcloud run services logs read google-ads-mcp \
  --region=europe-west4 --project=
 --limit=200 \
  | grep tool_

______________________________________________________________________