完整的Google Ads API v21 MCP服务器

🎉 完全可用的 -40多种工具实现了完全自动化！

全面的模型上下文协议（MCP）服务器，提供对Google Ads API v21功能的完全访问。该服务器使AI助手能够通过自然语言命令完全自动化地创建、优化和管理Google广告活动。

🚀 是什么让这与众不同

这是一个完整的实现！ 与其他只提供界面而不提供实现的存储库不同，每个工具实际上都与Google Ads API v21完全兼容：

✅ 已实施40+个工具 -完全的活动自动化\ ✅ 100%API v21兼容 -所有最新功能和修复\ ✅ 生产测试 -成功管理大规模的真实活动\ ✅ 高级自动化 -从创建到优化的完整活动生命周期\ ✅ 全面的错误处理 -强大的重试逻辑和详细的错误\ ✅ 完整的文件 -示例和语法指南

🛠️ 全套工具（45+工具）

🏢 账户管理（3个工具）

list_accounts -列出所有可访问的Google Ads帐户
get_account_info -具有优化分数的详细帐户信息
get_account_hierarchy -完整的账户结构和关系

🎯 活动管理（10个工具）

create_campaign -创建具有高级定位和竞价功能的活动
update_campaign -更新设置，包括投资组合竞价策略分配
pause_campaign / resume_campaign -活动生命周期管理
list_campaigns -使用性能数据过滤和搜索活动
get_campaign -全面的活动细节和指标
delete_campaign -安全活动移除
copy_campaign -具有新预算的重复活动
create_ad_schedule -提前分日调整出价
get_campaign_overview -显示活动结构、关键字、扩展、优化分数的完整仪表板

📁 广告组管理（3个工具）

create_ad_group -使用自定义竞价创建广告组
update_ad_group -修改广告组设置和出价
list_ad_groups -使用过滤器浏览广告组

📝 高级广告管理（10个工具）

create_responsive_search_ad -现代响应式搜索广告
create_expanded_text_ad -传统的扩展文本广告
list_ads / update_ad / pause_ad / enable_ad / delete_ad -完整的广告生命周期
compare_ad_performance -并排广告性能分析
get_ad_group_performance_ranking -按效率指标对广告进行排名
identify_optimization_opportunities -基于AI的优化建议
calculate_roas_by_ad -广告支出回报分析与盈利能力洞察

🧠 关键词智能（8个工具）

add_keywords -添加具有自定义匹配类型和出价的关键字
add_negative_keywords -具有智能protobuf处理的活动/广告组负面关键字
list_keywords -带有质量分数和绩效数据的关键词
update_keyword_bid / delete_keyword / pause_keyword / enable_keyword -完成关键字生命周期
get_keyword_performance -质量分数和优化见解

🎨 现代扩展（6工具）

create_sitelink_extensions -带有说明的附加链接（API v21 AssetService）
create_callout_extensions -引人注目的标注文本（与API v21兼容）
create_structured_snippet_extensions -带有标头验证的服务展示
create_call_extensions -带日程安排的电话分机
list_extensions / delete_extension -扩展管理

💰 组合投标（5种工具）

create_portfolio_bidding_strategy -目标CPA、ROAS、印象分享策略
list_bidding_strategies -带有活动任务的投资组合策略
set_bid_adjustments -设备、位置、人口统计出价修改
get_bid_adjustment_performance -投标调整投资回报率分析
get_device_performance -移动/台式机/平板电脑性能细分

🚀 关键能力

🎯 完成活动自动化

从头开始创建完全优化的活动：

智能竞价：目标印象份额、目标注册会计师、目标ROAS投资组合策略
高级排程：确定营业时间，分日调整投标
扩展自动化：网站链接、标注、带验证的结构化代码片段
受众智能：再营销列表、用户兴趣、智能受众检测
负面关键词智能：自动浪费术语检测和建议

🧠 AI驱动的优化

活动健康评分：100分优化评估，包括详细细分
性能分析：ROAS计算、效率评分、随时间变化的趋势分析
自动推荐：出价调整、关键字建议、受众优化
搜索词智能：将浪费的搜索查询自动转换为负面关键字
地理优化：基于地点的投标调整和目标建议

🔧 高级技术功能

Google Ads API v21完全兼容：现代AssetService，消除了弃用的API
智能错误处理：指数回退、部分故障恢复、详细的错误文档
智能现场验证：自动创建protobuf对象、字段验证、枚举处理
身份验证灵活性：OAuth2、服务帐户、令牌刷新、多帐户管理器支持
资源管理：自动资源名称构造，跨资源关系处理

📋 完成安装和设置

先决条件

Python 3.10+
具有API访问权限的Google Ads帐户
开发人员令牌（基本或标准访问）

安装

# Clone the repository
git clone https://github.com/grantweston/google-ads-mcp-complete.git
cd google-ads-mcp-complete

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Google Ads API设置

获取开发者令牌:

- 登录Google Ads帐户 - 转到“工具和设置”→ API中心 - 申请开发者令牌（建议使用基本访问权限）

创建OAuth2凭据:

- 访问 Google 云控制台 - 创建/选择项目→ 启用Google Ads API - 创建OAuth 2.0客户端ID（桌面应用程序） - 下载客户端凭据

配置

创建 config.json 在项目根目录中：

{
  "client_id": "YOUR_OAUTH_CLIENT_ID",
  "client_secret": "YOUR_OAUTH_CLIENT_SECRET", 
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "developer_token": "YOUR_DEVELOPER_TOKEN",
  "login_customer_id": "YOUR_MANAGER_ACCOUNT_ID",
  "use_proto_plus": true
}

MCP集成

添加到Claude桌面配置(~/.claude/mcp.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/google-ads-mcp-complete/run_server.py"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ID"
      }
    }
  }
}

💡 高级用例

🎯 完成活动自动化

"Create a comprehensive search campaign for 'AI productivity tools' with:
- $100 daily budget targeting US business professionals
- Target Impression Share bidding for positions 3-4
- Business hours scheduling with +20% mobile bid adjustment  
- Complete extension suite (sitelinks, callouts, structured snippets)
- Negative keyword protection against irrelevant traffic
- Remarketing audience targeting in observation mode"

📊 性能优化

"Analyze all campaigns and:
- Generate negative keyword suggestions from wasteful search terms
- Optimize geographic targeting based on conversion data
- Create portfolio bidding strategy for underperforming campaigns
- Identify top-performing ads for scaling
- Calculate ROAS by ad with profitability recommendations"

🎨 扩展管理

"Add comprehensive extensions to all search campaigns:
- Sitelinks for Features, Pricing, Demo, Support pages
- Callouts highlighting key benefits and trust signals
- Structured snippets showcasing service categories  
- Call extensions with business hours scheduling"

📈 真实世界结果

经验证的生产性能：

✅ 每个活动84+个扩展 （网站链接、标注、结构化片段）
✅ 100/100优化分数 完全自动化
✅ 投资组合投标策略 跨多个活动分配
✅ 高级排程 营业时间和出价调整
✅ 精准的受众定位 具有再营销和用户兴趣

🔧 Google Ads API v21兼容性

此MCP服务器针对Google Ads API v21进行了全面更新，采用了现代最佳实践：

✅ 已应用API v21更新

现代扩展：从已弃用的ExtensionFeedItemService迁移到AssetService+CampaignAssetService
投标策略：修复了设备定位问题，添加了带有location_faction_micros的TARGET_IMPRESSION_SHARE
现场兼容性：已删除已弃用 metrics.conversion_rate，修复了protobuf对象的创建
错误处理：更新了v21错误代码和响应格式
资源管理：现代资源名称构建和验证

🔐 身份验证和安全

多种身份验证方法：OAuth2、服务帐户、环境变量
令牌自动刷新：自动更新OAuth令牌并恢复错误
凭据缓存：TTL过期的安全凭据存储
多账户支持：经理帐户层次结构处理
费率限制管理：智能请求限制和队列管理

🧪 开发与测试

运行服务器

# Development mode with debug logging
export LOG_LEVEL=DEBUG
python run_server.py

# Production mode
python run_server.py

测试工具

# Run comprehensive test suite
pytest tests/

# Test specific tool functionality
python -c "
from src.tools_complete import GoogleAdsTools
from src.auth import GoogleAdsAuthManager  
from src.error_handler import ErrorHandler

auth = GoogleAdsAuthManager()
tools = GoogleAdsTools(auth, ErrorHandler()) 
print(f'Available tools: {len(tools.get_all_tools())}')
"

安全说明

从不将凭据提交到版本控制
在生产环境中使用服务帐户
在Google Ads帐户上启用2FA
定期轮换刷新令牌
监控API使用情况并设置警报

🏗️ 建筑与技术卓越

模块化设计

src/
├── server.py              # MCP server core with resource handlers
├── auth.py                # OAuth2 & Service Account authentication  
├── error_handler.py       # Retry logic & Google Ads error processing
├── tools_complete.py      # Central tool registry and orchestration
├── tools_campaigns.py     # Campaign CRUD, scheduling, overview dashboard
├── tools_bidding.py       # Portfolio strategies, bid adjustments, device targeting
├── tools_keywords.py      # Keyword management, negative keyword intelligence
├── tools_extensions.py    # Modern AssetService-based extensions
├── tools_ads.py          # Ad creation, optimization analysis, ROAS calculation
├── tools_audiences.py     # Audience targeting with smart ID detection
├── tools_assets.py       # Image/text asset management
├── tools_budgets.py      # Shared budget management
├── tools_geography.py    # Location targeting and geo-optimization
├── tools_reporting.py    # Performance analytics and custom reporting
└── utils.py              # Currency conversion, date parsing, formatting

企业级功能

智能类型检测：自动检测受众类型，验证枚举值
后备处理：API查询失败时的优雅降级
资源名称管理：自动构建Google Ads资源名称
Protobuf安全：正确的Google Ads protobuf对象创建和验证
性能优化：缓存、连接池、高效批处理操作

📊 生产性能

大规模的真实活动管理：

✅ 45+工具 涵盖完整的Google Ads API v21功能
✅ 100%成功率 在活动创建和优化中
✅ 每个活动84+个扩展 自动创建和管理
✅ 完全自动化 从活动创建到绩效优化
✅ 企业可靠性 具有全面的错误处理和重试逻辑

许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

开发工作流程

分叉存储库
创建特征分支(git checkout -b feature/amazing-feature)
为新功能添加全面的测试
确保Google Ads API v21的兼容性
提交带有详细描述的拉取请求

代码规范

类型提示：全类型注释覆盖率
错误处理：使用结构化日志记录进行全面的异常处理
文档：所有公共方法的详细文档字符串
测试：所有工具功能的单元测试
API兼容性：确保v21字段兼容性和正确的protobuf处理

添加自定义工具

在适当的模块中创建工具方法（例如。， tools_campaigns.py)
在中添加工具注册 tools_complete.py
添加全面的错误处理和验证
更新文档和语法示例

🆘 支持和故障排除

常见问题

认证：检查开发人员令牌、客户端凭据和帐户访问级别
速率限制：监控API使用情况，实现请求节流
字段错误：验证Google Ads API v21字段兼容性和枚举值
资源名称：确保正确的资源名称格式构造
Protobuf错误：检查对象创建模式和所需字段验证

错误处理功能

智能错误恢复：具有智能重试逻辑的指数回退
详细的错误文档：链接到Google Ads API错误指南和解决方案
部分故障处理：当某些操作失败时继续处理
智能重试逻辑：区分可重试错误和永久错误

获取帮助

检查错误消息以获取文档链接和建议
审查 Google Ads API文档
打开GitHub问题，提供详细的错误信息和日志
检查服务器日志以获取具有相关ID的详细调试信息

______________________________________________________________________

🚀 生产就绪 | 🔧 Google Ads API v21兼容 | 🤖 完成活动自动化

使用最全面的MCP服务器转换您的Google广告管理-从广告系列创建到高级优化，所有这些都是通过自然语言AI命令完成的。

Google Ads MCP Complete

快速接入

详细介绍

完整的Google Ads API v21 MCP服务器

🚀 是什么让这与众不同

🛠️ 全套工具（45+工具）

🏢 账户管理（3个工具）

🎯 活动管理（10个工具）

📁 广告组管理（3个工具）

📝 高级广告管理（10个工具）

🧠 关键词智能（8个工具）

🎨 现代扩展（6工具）

💰 组合投标（5种工具）

🚀 关键能力

🎯 完成活动自动化

🧠 AI驱动的优化

🔧 高级技术功能

📋 完成安装和设置

先决条件

安装

Google Ads API设置

配置

MCP集成

💡 高级用例

🎯 完成活动自动化

📊 性能优化

🎨 扩展管理

📈 真实世界结果

🔧 Google Ads API v21兼容性

✅ 已应用API v21更新

🔐 身份验证和安全

🧪 开发与测试

运行服务器

测试工具

安全说明

🏗️ 建筑与技术卓越

模块化设计

企业级功能

📊 生产性能

许可证

🤝 贡献

开发工作流程

代码规范

添加自定义工具

🆘 支持和故障排除

常见问题

错误处理功能

获取帮助

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP