用自然语言管理 Google Ads 广告投放 - 专为 Claude Code 设计的对话式 CLI 工具
npm install @optima-chat/google-ads-cli> 为客户创建和管理 Google Ads 广告的专业工具 - 专为服务提供商和 Claude Code 设计





本工具专为 Google Ads 广告主设计,让您轻松管理自己的广告投放。
- 🎯 客户专用 - 安装在客户环境,管理自己的 Google Ads 账号
- 🚀 一键注册 - 通过 CLI 创建账号,自动发送邀请邮件
- ⚡ 自动配置 - 账号信息自动保存,无需手动输入 Customer ID
- 🤖 AI 友好 - 可被 Claude Code 自然语言调用,对话式管理广告
- 📊 完整功能 - 创建/查看/删除广告系列、广告组、关键词等
- 🎯 单账号模式 - 专为客户设计,一键配置自动保存
- 📢 广告投放管理 - 创建广告系列、广告组、关键词
- 📊 效果分析 - 查看广告表现数据
- ⚡ 直接调用 - 使用 Google Ads API 官方 SDK v21
- 📋 多格式输出 - 表格、JSON 格式支持
- 🔐 OAuth2 认证 - 完整的 OAuth2 授权流程,自动 token 刷新
- ⚙️ 配置管理 - CLI config 自动管理账号信息
- 💎 架构简洁 - TypeScript + Google Ads API,无额外依赖
``bash安装
npm install -g @optima-chat/google-ads-cli@latest
$3
#### 方式 1: 非交互式模式(推荐 AI/自动化使用)
`bash
一次性提供所有参数(无需交互)
google-ads account create \
--email your@gmail.com \
--name "Your Company Name" \
--customer-id 1234567890 \
--jsonCustomer ID 从哪里来?
1. 访问 https://ads.google.com/
2. 用 Gmail 登录,切换到"专家模式"
3. 创建账号(不创建广告系列)
4. 记录 Customer ID(10位数字)
`#### 方式 2: 交互式模式(人类用户)
`bash
运行命令,CLI 会引导你创建账号
google-ads account create --email your@gmail.com --name "Your Company Name"CLI 会:
1. 显示手动创建步骤(引导在 Google Ads UI 中操作)
2. 交互式提示输入 Customer ID
3. 自动保存配置到 CLI config
`#### 完成创建后
`bash
验证账号配置
google-ads account check
`下一步:
- 检查邮箱中的 Google Ads 邀请邮件
- 点击邮件中的链接接受邀请
- 登录 Google Ads 设置账单信息
详细教程:
- 客户创建账号:
docs/客户创建账号指南.md
- AI 使用指南:docs/AI-使用指南.md$3
`bash
查看广告系列
google-ads campaign list创建广告系列
google-ads campaign create -n "我的广告系列" -b 50查看关键词
google-ads keyword list执行 GAQL 查询分析广告表现
google-ads query -q "SELECT campaign.id, campaign.name, metrics.impressions FROM campaign" --pretty
`$3
`bash
查看当前配置
google-ads config show重置配置(重新创建账号)
google-ads config reset查看配置文件路径
google-ads config path
`使用示例
$3
`bash
1. 创建广告系列
google-ads campaign create -n "春季促销活动" -b 1002. 创建广告组
google-ads ad-group create --campaign-id 12345678 -n "iPhone 15" -b 2.53. 添加关键词
google-ads keyword add 98765432 --keywords "iPhone 15,iPhone 15 Pro,苹果手机"4. 查看广告系列表现
google-ads query -q "SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS" --pretty5. 暂停表现不佳的广告系列
google-ads campaign delete 12345678
`$3
Claude Code 可以直接调用这些命令:
`
你:帮我创建一个预算 50 美元的春季促销广告系列
Claude:google-ads campaign create -n "春季促销" -b 50你:查看最近 7 天表现最好的 5 个广告系列
Claude:google-ads query -q "SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.clicks DESC LIMIT 5" --pretty
`架构
`
Agency (提供 MCC 凭据)
↓
客户安装 google-ads-cli
↓
运行 account create → 创建子账号 + 发送邀请
↓
客户接受邀请 + 设置账单
↓
Claude Code / AI 调用 CLI
↓
google-ads-cli (TypeScript)
↓ (Google Ads API SDK)
Google Ads API
↓
客户的 Google Ads 账号
`设计理念:
- Agency 提供 MCC 凭据,客户使用 CLI 创建自己的子账号
- 账号信息自动保存到 CLI config,无需手动配置
- 每个客户独立管理自己的广告,互不影响
- 架构简洁,客户体验流畅
配置说明
$3
由 Agency 提供,客户只需复制粘贴到
.env 文件:`bash
Developer Token(Agency 提供)
GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-tokenOAuth2 客户端凭据(Agency 提供)
GOOGLE_ADS_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET=your-client-secretMCC 管理账号 ID(Agency 提供)
GOOGLE_ADS_MANAGER_ACCOUNT_ID=123-456-7890OAuth2 Refresh Token(运行 google-ads auth login 后自动生成)
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
`$3
运行
google-ads account create 后,以下信息会自动保存:- Customer ID(您的 Google Ads 账号 ID)
- 账号名称
- 货币代码
- 时区
- 邮箱地址
配置文件位置:
~/.config/google-ads-cli/config.json查看配置:
google-ads config show$3
1. 创建 MCC 账号:访问 https://ads.google.com
2. 获取 Developer Token:访问 https://ads.google.com/aw/apicenter
3. 配置 OAuth2:
- 访问 https://console.cloud.google.com
- 创建项目并启用 Google Ads API
- 创建 OAuth 2.0 客户端 ID(桌面应用类型)
- 获取 Client ID 和 Client Secret
命令概览
$3
- google-ads --version - 查看版本
- google-ads --help - 查看帮助$3
- login - OAuth2 登录
- logout - 退出登录
- status - 查看认证状态$3
- create --email ] [--timezone ] - 创建您的 Google Ads 账号
- check [--json] - 检查账号配置状态(账单、权限等)$3
- list [--status ] [--limit ] [--json] - 列出广告系列
- info [--json] - 查看广告系列详情
- create -n -b [--status ] - 创建广告系列
- delete - 删除广告系列$3
- list --campaign-id [--json] - 列出广告组
- create --campaign-id -n -b - 创建广告组
- delete - 删除广告组$3
- list [--campaign-id ] [--status ] [--limit ] [--json] - 列出关键词
- add --keywords [--match-type ] - 添加关键词
- delete - 删除关键词$3
- show [--json] - 显示当前配置
- reset [--force] - 重置配置
- path - 显示配置文件路径$3
- query -q "" [--json] [--pretty] - 执行 GAQL 查询
- query -f [--json] [--pretty] - 从文件执行查询查看 完整命令文档 了解更多。
双模式设计
$3
简单、明确、LLM 易理解`bash
管理您的广告
google-ads campaign list
google-ads campaign create -n "广告系列名称" -b 100
google-ads keyword add --keywords "产品关键词1,产品关键词2"
`$3
灵活、强大、适合复杂分析`bash
google-ads query "
SELECT
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.clicks DESC
"
`版本说明
当前版本:v0.4.0
$3
- ✅ 客户专用架构(单账号模式)
- ✅ OAuth2 认证(login/logout/status)
- ✅ 混合配置管理(.env + CLI config)
- ✅ 账号管理(account create/check)
- ✅ 配置管理(config show/reset/path)
- ✅ 广告系列管理(campaign list/info/create/delete)
- ✅ 广告组管理(ad-group list/create/delete)
- ✅ 关键词管理(keyword list/add/delete)
- ✅ GAQL 查询支持(query)
- ✅ 自动发布到 NPM
$3
- 🚧 账号创建 API 调用(当前通过 UI 手动创建 + CLI 保存配置)
- 🚧 广告文案管理命令
- 🚧 效果分析和报表命令
$3
1. 账号创建:当前需要手动在 Google Ads UI 中创建账号,然后通过 CLI 保存配置。API 自动创建功能正在开发中。
2. EU 政治广告:创建广告系列时默认设置为不包含 EU 政治广告(符合 2025 年 9 月新规)
3. 单账号模式:每个客户只能配置一个 Google Ads 账号,如需管理多账号请使用
google-ads config reset 切换相关项目
- gaql-cli - GAQL 查询工具(设计参考)
- optima-cli - 电商管理 CLI(技术栈参考)
技术栈
- CLI 框架: commander.js
- HTTP 客户端: axios
- 输出格式化: chalk + cli-table3
- 交互提示: inquirer
- 配置管理: conf
- 开发工具: TypeScript + tsx
发布流程
本项目使用 GitHub Actions 自动发布到 NPM:
`bash
更新版本号(patch/minor/major)
npm version patch推送 tag 触发自动发布
git push --follow-tags
``GitHub Actions 会自动:
- 运行测试和构建
- 发布到 NPM
- 创建 GitHub Release
- 生成 changelog
查看最新发布:https://github.com/Optima-Chat/google-ads-cli/releases
贡献
欢迎提交 Issue 和 Pull Request!
许可证
MIT License - 详见 LICENSE
联系我们
- 官网: https://www.optima.shop
- 社区: https://optima.chat
- GitHub: https://github.com/Optima-Chat/google-ads-cli