Mcp Google Ads

mcp-google-ads

面向运营人员的多账号 Google Ads MCP 服务，无需重启服务，即可通过一个 MCP 接口管理多个客户或内部广告账号。

发布状态：测试版软件包，版本为 pyproject.toml 中的 0.1.0。

选择你的路径

你要……	从这里开始	然后
将服务连接到 MCP 客户端	docs/start-here.md	查看下方的快速入门
审查账号切换和重试机制	docs/architecture.md	gads/server.py
审查打包元数据	pyproject.toml	accounts.example.json

架构

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> S[FastMCP server]
  S --> M[Account manager]
  M --> F[Accounts config]
  S --> Q[GAQL query helpers]
  Q --> R[Retry wrapper]
  R --> A[Google Ads API]
  A --> R --> S

请求流程

flowchart TD
  P[Operator asks for account or campaign data] --> T[Selected MCP tool]
  T --> A[Resolve named or default account]
  A --> B[Build Google Ads client]
  B --> C[Run GAQL query]
  C --> D{API call succeeds?}
  D -- yes --> E[Normalize rows and return]
  D -- retryable --> F[Backoff and retry]
  F --> D
  D -- no --> G[Return error payload]

快速入门

1. 安装软件包。

python -m pip install mcp-google-ads-multi

2. 复制账号配置模板并添加账号。

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json

3. 在 MCP 客户端中注册该服务。

{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["mcp-google-ads-multi"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
      }
    }
  }
}

可用工具

工具组	工具	用途
账号选择	list_accounts, set_default_account, list_customers	管理账号路由并发现可访问的客户
支出摘要	get_account_summary, compare_periods	按周期对比账号报告
广告系列分析	list_campaigns, get_campaign_performance	广告系列清单和按范围统计指标
查询级详情	get_keyword_performance, search_terms_report, get_ad_performance	关键词、搜索词和广告报告

运行时验证

声明	依据
软件包入口点稳定	pyproject.toml 中的 mcp-google-ads-multi = "gads.server:main"
多账号路由是核心功能	gads/server.py 中的 AccountManager() 和 set_default_account()
查询通过可复用的辅助函数执行	gads/query.py 和 gads/retry.py
配置由文件驱动	accounts.example.json 说明了账号配置结构

仓库目录

路径	用途
gads/server.py	FastMCP 工具接口
gads/accounts.py	账号配置、OAuth／服务账号加载
gads/query.py	GAQL 执行辅助函数
gads/retry.py	API 调用的重试行为
docs/start-here.md	设置、验证和常见故障
docs/architecture.md	组件图和请求生命周期

验证

检查项	命令
导入编译通过	python -m compileall gads
软件包构建成功	python -m build
README／文档链接均为本地链接	rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

许可证

MIT

新任务的项目背景

使用 INDEX.md 查找特定任务的约定；产品方向相关时，请查阅 prompt.md。历史示例不决定当前任务。