内容
谷歌广告管理工具
[](https://github.com/Limetric/goads/actions/workflows/ci.yml)
**活动管理工具 — Go 命令行界面和 MCP 服务器**
它与 **REST API** （无 gRPC，无 protobuf 代码生成）通信单个二进制文件与两个前端共享一组工具：
- **命令行界面** — `goads search …`，`goads accounts`，`goads budget set …`。可脚本化，可通过管道传输到 `jq`，可在 CI 中使用。这是捆绑代理 **技能** 所驱动的工具。
- **MCP 服务器** — `goads mcp` 通过 stdio 向 MCP 主机（Claude Desktop，Cursor，…）提供相同的工具。
## 快速入门
在 macOS 和 Linux 上，从 Limetric Homebrew 软件源安装 `goads`：
```bash
brew install Limetric/tap/goads
```
最快的设置方法是使用引导式登录 — 它引导您完成 Google Cloud 和开发者令牌的先决条件，通过浏览器登录并验证连接：
```bash
goads login # 交互式：从头开始引导您，然后进行验证
```
更喜欢手动配置（或在 CI 中）？直接设置环境变量并使用 `--no-input` 跳过向导：
```bash
go mod tidy
go build -o build/goads .
export GOOGLE_ADS_DEVELOPER_TOKEN=...
export GOOGLE_ADS_CLIENT_ID=...
export GOOGLE_ADS_CLIENT_SECRET=...
export GOOGLE_ADS_REFRESH_TOKEN=...
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890 # 可选的管理帐户
build/goads doctor # 验证凭证是否有效
build/goads accounts # 列出可访问的帐户
build/goads search --customer-id 123-456-7890 \
--query 'SELECT campaign.id, campaign.name FROM campaign LIMIT 10' | jq
```
大多数情况下都使用一个帐户？设置默认帐户一次并删除 `--customer-id`：
```bash
goads config set-customer 123-456-7890 # 或：export GOOGLE_ADS_CUSTOMER_ID=123-456-7890
goads campaigns # 使用默认帐户
goads config show # 查看已解析的配置（机密）
```
读取命令默认打印 JSON；传递 `--format table` 或 `--format csv` 以获取人类或电子表格友好的输出：
```bash
goads campaigns --format table
```
写入操作首先预览，然后使用返回的令牌应用：
```bash
goads budget set --budget-id 555 --amount-micros 5000000
# → 打印预览和确认令牌，例如 a1b2c3d4e5a7bgoads confirm a2c3d4e5f6b8 # 应用预览的更改
audit # 应用日志
```
运行原始命令并使用 `--confirm <token仍然有效。）
## 作为 MCP 服务器
将您的 MCP 主机指向二进制文件：
```json
{
"mcpServers": {
"goads": {
": "/path/to/build/goads",
"args": ["mcp"],
"env": {
"GOOGLE_ADS_DEVELOPER_TOKEN": "...",
"GOOGLE_ADS_CLIENT_ID": "...",
"GOOGLE_ADS_CLIENT_SECRET": "...",
"GOOGLE_ADS_REFRESH_TOKEN": "...",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "..."
}
}
}
}
```
## 作为 Claude Code 技能
存储库捆绑了一个技能（`plugins/goads/skills/goads/SKILL.md`，在 `.claude/skills/goads` 中为贡献者提供符号链接），该技能教导代理如何驱动命令行界面 — 由于只有在相关时才会加载，因此令牌效率高，而大结果集保留在 shell（`| jq`）中，而不是上下文窗口中。
如果您通过 Homebrew 安装了 `goads`没有克隆存储库，请作为 Claude Code 插件：
```text
/plugin marketplace add Limetric/goads
/plugin install goads@goads
```
##x 插件
Codex 通过其自己的插件清单读取相同的技能：
```bash
codex plugin marketplace add Limetric/goads
codex plugin add goads@goads
```
## 工具覆盖
全面的活动管理加上首屈一指的应用活动创建可用（48 个 MCP 工具 / 等效的命令行界面命令）：
- **读取** — `search`，`report`，`accounts` （+ `accounts info` 用于货币/时区），`campaigns`，`ads`，关键词性能/搜索词/否定，`geo` 搜索 + 性能，`conversions`，`policy`，`extensions`，关键词规划师创意 + 预测，和推荐列表。行返回读取呈现为 `--formattable|csv` **写入** （所有预览然后确认）— 搜索，应用和性能最大化活动创建/更新，广告组创建/更新，RSA 起草，关键词添加/删除 （+ 否定），出价策略 + 关键词出价，站点链接/标语/片段扩展，观众，图像/文本资产，广告调度，性能最大化活动，暂停/启用/删除，和推荐应用/解除。
写入安全性：每个突变首先预览，只有在确认后才应用（`goads confirm <token>` 或重新运行带有 `--confirm`）；`goads audit` 显示每个已应用的写入；客户端允许列表拒绝无效的 `googleAds:mutate` 操作键；并且可以通过 `GOOGLE_ADS_MAX_DUDGET`，`GOOGLE_ADS_MAX_BID_INCREASE_PCT` 和 `GOOGLE_ADS_BLOCKED_OPS` 配置防护栏（支出上限，出价增加限制，阻止操作列表）。新活动/广告组/情况下处于 **暂停** 状态。
## Shell 补全
安装补全。对于，`goads completion` 为您的 shell 生成脚本：
```bash
# bash（需要 bash）
goads completion bash > /usr/local/etc/bash_completionads
# zsh
goads completion zsh > "${fpath[1]}/_goads"
# fish
go fish > ~/.config/fish/completions/goads.fish
```
在 [`AG
