Google Ads自然语言管理服务器

"Initialize my Google Ads connection with these credentials..."
"Show me all my Google Ads accounts"
"Analyze campaign performance for the last 30 days"
"Which keywords have the lowest quality scores?"

python generate_refresh_token.py

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_ID = 'your-client-id.apps.googleusercontent.com'
CLIENT_SECRET = 'your-client-secret'
SCOPES = ['https://www.googleapis.com/auth/adwords']

flow = InstalledAppFlow.from_client_config(
    {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    },
    scopes=SCOPES
)

credentials = flow.run_local_server(port=0)
print(f"Refresh Token: {credentials.refresh_token}")

pip install -r requirements.txt

pip install google-ads>=25.0.0 mcp>=1.1.0 httpx>=0.27.0 pydantic>=2.0.0 google-auth-oauthlib>=1.0.0

# Caching with Redis
pip install redis>=5.0.0

# Export and reporting
pip install openpyxl>=3.1.2 reportlab>=4.0.0 matplotlib>=3.8.0

python -c "import google.ads.googleads, mcp, httpx, pydantic; print('All dependencies installed successfully!')"

{
  "developer_token": "string (required)",
  "client_id": "string (required)",
  "client_secret": "string (required)",
  "refresh_token": "string (required)",
  "login_customer_id": "string (optional)"
}

Initialize with:
- Developer Token: abc123...
- Client ID: 123456789.apps.googleusercontent.com
- Client Secret: xyz789...
- Refresh Token: 1//abc...
- Login Customer ID: 1234567890 (only for MCC accounts)

{
  "response_format": "markdown | json (default: markdown)"
}

"Show me all my Google Ads accounts"
"List accounts in JSON format"

{
  "customer_id": "string (required, 10 digits no hyphens)",
  "date_range": "TODAY | YESTERDAY | LAST_7_DAYS | LAST_30_DAYS | etc. (default: LAST_30_DAYS)",
  "campaign_status": "ENABLED | PAUSED | REMOVED (optional)",
  "min_cost": "number (optional, in account currency)",
  "limit": "number (default: 50, max: 100)",
  "response_format": "markdown | json (default: markdown)"
}

"Show campaign performance for the last 30 days for account 1234567890"
"Find campaigns with at least $100 in spend this month"
"Show only enabled campaigns for account 1234567890"

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "min_impressions": "number (optional)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

"Analyze keyword performance for campaign 12345"
"Show keywords with quality score below 5"
"Find keywords with the highest cost per conversion"

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "min_impressions": "number (default: 10)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

"What search terms triggered my ads in the last 30 days?"
"Find high-impression search terms with low CTR"
"Show search terms for campaign 67890"

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

"Show ad group performance for all campaigns"
"Find best-performing ad groups in campaign 12345"

{
  "customer_id": "string (required)",
  "recommendation_types": "array of strings (optional)",
  "limit": "number (default: 20)",
  "response_format": "markdown | json"
}

"Show optimization recommendations for account 1234567890"
"What does Google suggest for improving my campaigns?"

{
  "customer_id": "string (required)",
  "campaign_id": "string (required)",
  "budget_amount_micros": "number (required, in micros)"
}

"Set campaign 12345 budget to $75 per day"
"Increase budget for campaign 67890 to 100,000,000 micros ($100)"

{
  "customer_id": "string (required)",
  "campaign_id": "string (required)",
  "status": "ENABLED | PAUSED (required)"
}

"Pause campaign 12345"
"Enable campaign 67890"

{
  "customer_id": "string (required)",
  "query": "string (required, valid GAQL query)",
  "response_format": "markdown | json"
}

"Execute this GAQL query: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000"

User: "Show me all my Google Ads accounts"

Claude: [Calls google_ads_list_accounts]
I can see you have 3 accessible Google Ads accounts:
1. Account 123-456-7890 (My Business)
2. Account 234-567-8901 (E-commerce Store)
3. Account 345-678-9012 (Client ABC)

User: "Analyze campaign performance for the last 30 days for my main account"

Claude: [Calls google_ads_campaign_performance with customer_id="1234567890"]
Here's the performance for your campaigns over the last 30 days:

Top Performers:
- Brand Campaign: $1,245 spent, 523 conversions, $2.38 CPA
- Shopping Campaign: $2,100 spent, 312 conversions, $6.73 CPA

Needs Attention:
- Generic Keywords: $850 spent, 12 conversions, $70.83 CPA (consider pausing)

User: "Show me keywords with quality score below 5 for campaign 12345"

Claude: [Calls google_ads_keyword_performance with filtering]
Found 8 keywords with quality scores below 5:

1. "cheap widgets" - QS: 3, Avg Pos: 4.2, $145 spent
   Suggestion: Improve ad relevance or pause
2. "buy widgets online" - QS: 4, Avg Pos: 3.8, $98 spent
   Suggestion: Create dedicated ad group with tailored ad copy
...

User: "Increase the budget for campaign 67890 to $150 per day"

Claude: [Calls google_ads_update_campaign_budget with budget_amount_micros=150000000]
Budget updated successfully:
- Campaign: Summer Sale 2025
- Old Budget: $100.00/day
- New Budget: $150.00/day
- Effective: Immediately

User: "What search terms are triggering my ads with high impressions but low CTR?"

Claude: [Calls google_ads_search_terms with analysis]
Found 15 search terms with >1000 impressions and CTR <1%:

High Priority:
1. "free widgets" - 5,234 impressions, 0.3% CTR
   Recommendation: Add as negative keyword
2. "how to make widgets" - 3,421 impressions, 0.5% CTR
   Recommendation: Add as negative keyword (informational intent)

from mcp import ClientSession
import asyncio

async def analyze_campaigns():
    async with ClientSession() as session:
        # Initialize connection
        await session.call_tool("google_ads_initialize", {
            "developer_token": "YOUR_TOKEN",
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_SECRET",
            "refresh_token": "YOUR_REFRESH_TOKEN"
        })

        # Get campaign performance
        result = await session.call_tool("google_ads_campaign_performance", {
            "customer_id": "1234567890",
            "date_range": "LAST_7_DAYS",
            "response_format": "json"
        })

        print(result)

asyncio.run(analyze_campaigns())

authentication:
  method: oauth2  # or service_account
  developer_token: ${GOOGLE_ADS_DEVELOPER_TOKEN}
  client_id: ${GOOGLE_ADS_CLIENT_ID}
  client_secret: ${GOOGLE_ADS_CLIENT_SECRET}
  refresh_token: ${GOOGLE_ADS_REFRESH_TOKEN}
  login_customer_id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID}  # Optional MCC

performance:
  cache:
    backend: memory  # Options: memory, redis, none
    ttl:
      accounts: 3600      # 1 hour
      campaigns: 300      # 5 minutes
      keywords: 300       # 5 minutes
      search_terms: 600   # 10 minutes
    redis_url: redis://localhost:6379/0  # If using Redis
    max_size: 1000  # For memory cache

  connection_pool:
    size: 10
    timeout: 30

  rate_limiting:
    enabled: true
    requests_per_minute: 60
    burst_size: 10

error_handling:
  retry:
    enabled: true
    max_attempts: 3
    backoff_strategy: exponential  # linear, exponential
    initial_delay: 1
    max_delay: 30

  alerts:
    webhook_url: https://your-webhook.com/alerts
    email: admin@example.com

  log_errors: true

logging:
  level: INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
  format: json  # json, text
  file: /var/log/google-mcp/server.log
  console: true

features:
  batch_operations: true
  auto_recommendations: true
  advanced_reporting: true
  conversion_tracking: true
  audience_management: true

api_version: v17  # Google Ads API version
default_page_size: 50
character_limit: 25000  # MCP response size limit

# Authentication
export GOOGLE_ADS_DEVELOPER_TOKEN="your-token"
export GOOGLE_ADS_CLIENT_ID="your-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"  # Optional

# Performance
export GOOGLE_MCP_CACHE_BACKEND="redis"
export GOOGLE_MCP_REDIS_URL="redis://localhost:6379/0"

# Logging
export GOOGLE_MCP_LOG_LEVEL="DEBUG"
export GOOGLE_MCP_LOG_FILE="/var/log/google-mcp.log"

features:
  batch_operations: true      # Bulk operations support
  auto_recommendations: true  # Google AI recommendations
  advanced_reporting: true    # 25+ specialized reports
  conversion_tracking: true   # Conversion management
  audience_management: true   # Remarketing, Customer Match

google-mcp/
├── google_ads_mcp.py              # Main MCP server (v1) - 10 tools
├── google_ads_mcp_v2.py           # Enhanced server (v2) - 161 planned tools
├── generate_refresh_token.py      # OAuth token generation utility
│
├── Infrastructure Managers
├── auth_manager.py                # OAuth authentication & token management
├── config_manager.py              # Configuration loading (YAML/JSON)
├── cache_manager.py               # Caching layer (Memory/Redis)
├── error_handler.py               # Error handling & retry logic
├── logger.py                      # Structured logging
├── response_handler.py            # Response formatting & streaming
├── query_optimizer.py             # GAQL query optimization
│
├── Domain Managers
├── campaign_manager.py            # Campaign creation & management
├── ad_group_manager.py            # Ad group operations
├── ad_manager.py                  # Ad creation & management
├── keyword_manager.py             # Keyword operations
├── bidding_strategy_manager.py    # Bidding strategy configuration
├── audience_manager.py            # Audience management
├── conversion_manager.py          # Conversion tracking
├── automation_manager.py          # Automated rules
├── batch_operations_manager.py    # Bulk operations
├── extensions_manager.py          # Ad extensions
├── labels_manager.py              # Label management
├── shopping_pmax_manager.py       # Shopping & Performance Max
├── local_app_manager.py           # Local & app campaigns
├── insights_manager.py            # Analytics & insights
├── reporting_manager.py           # Advanced reporting
│
├── MCP Tool Registrations
├── mcp_tools_campaigns.py         # Campaign tools
├── mcp_tools_ad_groups.py         # Ad group tools
├── mcp_tools_ads.py               # Ad tools
├── mcp_tools_keywords.py          # Keyword tools
├── mcp_tools_bidding.py           # Bidding tools
├── mcp_tools_audiences.py         # Audience tools
├── mcp_tools_conversions.py       # Conversion tools
├── mcp_tools_automation.py        # Automation tools
├── mcp_tools_batch.py             # Batch operation tools
├── mcp_tools_extensions.py        # Extension tools
├── mcp_tools_shopping_pmax.py     # Shopping/PMax tools
├── mcp_tools_local_app.py         # Local/App tools
├── mcp_tools_insights.py          # Insights tools
├── mcp_tools_reporting.py         # Reporting tools
│
├── Configuration
├── config.yaml                    # Server configuration
├── config.example.yaml            # Configuration template
├── requirements.txt               # Python dependencies
│
├── Documentation
├── README.md                      # This file
├── SECURITY.md                    # Security policy
├── CONTRIBUTING.md                # Contribution guidelines
├── LICENSE                        # MIT License
├── CITATION.cff                   # Citation information
├── CODEOWNERS                     # Code ownership
├── documentation/                 # Additional documentation
│   ├── QUICKSTART.md
│   ├── IMPLEMENTATION_PLAN.md
│   ├── EXECUTIVE_SUMMARY.md
│   └── ...
│
└── .claude/                       # Claude Code configuration
    ├── claude_project.json
    └── CLAUDE.md

class CampaignManager:
    """Handles campaign-related operations."""

    def __init__(self, client: GoogleAdsClient, config: Config):
        self.client = client
        self.config = config

    def create_campaign(...) -> dict:
        """Create a new campaign."""
        # Validation
        # API operation
        # Error handling
        # Response formatting

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("google_ads_mcp")

@mcp.tool()
def google_ads_create_campaign(request: CampaignCreateRequest) -> dict:
    """Create a new Google Ads campaign."""
    manager = CampaignManager(client, config)
    return manager.create_campaign(**request.dict())

Initialize my Google Ads connection with these credentials:
- Developer Token: YOUR_TOKEN
- Client ID: YOUR_CLIENT_ID
- Client Secret: YOUR_SECRET
- Refresh Token: YOUR_REFRESH_TOKEN

import logging
logging.basicConfig(level=logging.DEBUG)

logging:
  level: DEBUG
  console: true
  file: /tmp/google-mcp-debug.log

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "developer_token": "YOUR_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "use_proto_plus": True
}

client = GoogleAdsClient.load_from_dict(credentials)
customer_service = client.get_service("CustomerService")
accessible_customers = customer_service.list_accessible_customers()
print(f"Accessible customers: {accessible_customers.resource_names}")

Initialize with:
- Login Customer ID: 1234567890 (your MCC ID)
- ...other credentials...

Then access client accounts:
"Analyze campaigns for client account 2345678901"
"List all accounts under my MCC"

SELECT
  resource.field1,
  resource.field2,
  metrics.metric1
FROM resource_name
WHERE conditions
ORDER BY field
LIMIT n

SELECT
  ad_group_criterion.keyword.text,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_micros
FROM keyword_view
WHERE
  metrics.impressions > 100
  AND campaign.status = 'ENABLED'
ORDER BY metrics.conversions DESC
LIMIT 20

MIT License

Copyright (c) 2025 John O'Connor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

O'Connor, J. (2025). Google Ads MCP Server (Version 1.0.0) [Computer software].
https://github.com/johnoconnor0/google-ads-mcp

@software{oconnor_google_mcp_2025,
  author = {O'Connor, John},
  title = {Google Ads MCP Server},
  year = {2025},
  version = {1.0.0},
  url = {https://github.com/johnoconnor0/google-ads-mcp}
}