gads (N Asuy)

年

用Rust编写的Google Ads API MCP服务器和CLI。

通过直接调用Google Ads REST API（v21） reqwest --没有gRPC依赖关系。 受启发于 googleads/gads python

安全通告

gads通过以下方式进行身份验证 Google Cloud应用程序默认凭据（ADC）. 一旦你跑了 gcloud auth application-default login，生成的凭据文件 (~/.config/gcloud/application_default_credentials.json)是a 机器范围广，寿命长 OAuth2刷新令牌。您计算机上的任何进程（不仅仅是gads）都可以读取此文件 并获得您授权的每个范围的访问令牌，包括Google Ads API 以及任何其他Google Cloud API。

使用小工具的风险由您自行承担。 您有责任保护您的本地凭据 并理解基于ADC的认证的含义。

看 路线图 计划缓解措施。

设置

1.谷歌云项目

# Install gcloud CLI if needed
# https://cloud.google.com/sdk/docs/install

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

2.启用Google Ads API

gcloud services enable googleads.googleapis.com

或通过启用 云控制台.

3.获取开发者令牌

1. 登录到…… Google广告
2. 工具和设置>设置>API中心
3. 复制开发人员令牌（初始访问权限仅限于测试帐户；生产需要批准）

细节：https://developers.google.com/google-ads/api/docs/get-started/dev-token

4.身份验证

选项A：应用程序默认凭据（推荐）

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/adwords"

这创造了 ~/.config/gcloud/application_default_credentials.json，gads会自动发现。

选项B：服务帐户

gcloud iam service-accounts create gads-sa \
  --display-name="gads service account"

gcloud iam service-accounts keys create sa-key.json \
  --iam-account=gads-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

您还必须在Google Ads中邀请服务帐户电子邮件： 工具和设置>访问和安全>添加服务帐户电子邮件。

5.环境变量

export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"

# Required only when accessing accounts via an MCC (Manager account)
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"

# Quota project for ADC user credentials (prevents 403)
export GOOGLE_CLOUD_QUOTA_PROJECT="your-gcp-project-id"

6.验证

cargo build -p gads --release

# List accessible accounts to confirm authentication
gads customers

构建

# Build host binary + npx tgz
bun run build

发布

# Patch version bump + build + publish
bun run release

CLI使用情况

不带参数（或带参数）运行 serve)启动MCP服务器。 子命令直接调用API。

gads [COMMAND]

Commands:
  serve      Start MCP server (stdio transport) [default]
  login      Authenticate via gcloud ADC with Google Ads API scope
  doctor     Diagnose auth, config, and API connectivity
  customers  List accessible customers with MCC/ACCOUNT labels
  use        Save/show default customer ID
  search     Execute a GAQL query
  campaign   Campaign operations (list / status)
  adgroup    Ad group operations (list / status)
  ad         Ad operations (list / status)
  creatives  List ad creatives (headlines, descriptions, URLs)
  mutate     Execute arbitrary mutate requests (create/update/delete)
  config     Manage persistent config (developer-token, login-customer-id)

客户

gads customers
gads customers --tree
gads customers --ids-only

医生

gads doctor

搜索

# Save a default customer ID first (optional)
gads use 1234567890

# Raw GAQL
gads search \
  -q "SELECT campaign.id, campaign.name FROM campaign" \
  -l 10

# Override login-customer-id for this command only
gads search \
  --customer-id 1234567890 \
  --login-customer-id 9988776655 \
  -q "SELECT campaign.id, campaign.name FROM campaign"

# Disable login-customer-id for this command
gads search \
  --customer-id 1234567890 \
  --no-login-customer-id \
  -q "SELECT campaign.id, campaign.name FROM campaign"

# Shorthand: resource + fields
gads search \
  --customer-id 1234567890 \
  -q "campaign campaign.id,campaign.name" \
  -l 10

输出是一个JSON数组。管道到 jq:

gads search -c 1234567890 -q "SELECT campaign.name FROM campaign" | jq '.[].["campaign.name"]'

使用

gads use 1234567890   # save default customer ID
gads use              # show current default

活动/广告组/广告/创意

gads campaign list -l 100
gads adgroup list -l 200
gads ad list -l 200
gads creatives -l 200

# Disable MCC header for this command
gads campaign --no-login-customer-id list

状态更新（已启用/已暂停）

gads campaign status --campaign-id 123456789 --status ENABLED
gads adgroup status --ad-group-id 987654321 --status PAUSED
gads ad status --ad-group-id 987654321 --ad-id 1122334455 --status ENABLED

# Validate only (dry run)
gads campaign status --campaign-id 123456789 --status ENABLED --validate-only

突变

呼叫 customers/{customer_id}/{service}:mutate 直接。 支持任何创建/更新/删除操作。

# Inline JSON
gads mutate \
  --service campaigns \
  --body '{
    "operations": [{
      "update": {
        "resourceName": "customers/1234567890/campaigns/111222333",
        "status": "ENABLED"
      },
      "updateMask": "status"
    }]
  }'

# From file + validate only
gads mutate \
  --service adGroupAds \
  --body-file ./mutate-body.json \
  --validate-only

MCP服务器使用情况

克劳德桌面/克劳德代码

{
  "mcpServers": {
    "gads": {
      "command": "/path/to/gads",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

MCP工具

建筑

src/
  main.rs      — Entry point (CLI parser + MCP serve)
  server.rs    — MCP tool registration + ServerHandler
  client.rs    — Google Ads REST API client
  auth.rs      — ADC token acquisition via gcp_auth
  query.rs     — GAQL query builder
  format.rs    — searchStream response flattening
  error.rs     — Unified error type
  gaql_resources.json — GAQL v21 field reference (compile-time embed)

测试

cargo test -p gads

路线图

• 范围凭证隔离 --当前ADC凭据授予对所有授权的访问权限

机器范围内。调查每个工具的凭据隔离（例如，短期令牌 范围仅限于 adwords 仅或中介令牌交换的代理），以便 受损的进程无法为无关的GCP API利用gads凭据。

• 令牌代理/代理架构 --代替直接读取ADC，gads可以

从强制范围、受众和生存期约束的本地代理请求令牌。 这将阻止其他进程重用原始刷新令牌。

• 凭证存储硬化 --探索纯文本ADC JSON文件的替代方案

（例如，操作系统密钥链集成、静态加密配置文件）。

• 审计日志 -使用时间戳和要检测的调用方上下文记录所有API调用

未经授权使用共享凭据。

许可证

麻省理工学院