@channel47/google-ads-mcp 1.0.0

package/server/prompts/templates.js

@@ -0,0 +1,231 @@
+/**
+ * Prompt templates for Google Ads MCP Server
+ * Each prompt defines a workflow that chains multiple tools together
+ */
+
+export const PROMPT_TEMPLATES = {
+  // Phase 2 prompt
+  quick_health_check: {
+    name: 'quick_health_check',
+    description: 'Fast daily check on account status',
+    arguments: [
+      {
+        name: 'customer_id',
+        description: 'Google Ads account ID (without dashes)',
+        required: true
+      }
+    ],
+    template: `Quick health check for Google Ads account {{customer_id}}:
+
+1. Yesterday's spend vs daily average - any anomalies?
+2. Any campaigns with $0 spend that should be running?
+3. Budget pacing - anything hitting limits early?
+4. Any new disapprovals or policy issues?
+5. Conversion tracking - are conversions recording normally?
+
+Just flag issues, don't deep-dive unless something's wrong.
+
+To complete this check:
+- Use get_performance with date_range YESTERDAY to see yesterday's metrics
+- Use budget_pacing to check for campaigns limited by budget
+- Compare yesterday's spend to the 7-day average
+- Flag any enabled campaigns with zero impressions or spend`,
+    requiredTools: ['get_performance', 'budget_pacing']
+  },
+
+  // Phase 3 prompt - fully functional
+  weekly_account_review: {
+    name: 'weekly_account_review',
+    description: 'Comprehensive weekly performance review for search and shopping campaigns',
+    arguments: [
+      {
+        name: 'customer_id',
+        description: 'Google Ads account ID (without dashes)',
+        required: true
+      }
+    ],
+    template: `Run a weekly account review for Google Ads account {{customer_id}}:
+
+1. Start with campaign-level performance for the last 7 days vs prior 7 days
+2. Identify the top 3 campaigns by spend and analyze their trend
+3. Check search terms report for wasted spend (high cost, no conversions)
+4. Review Quality Score distribution - flag any high-spend keywords with QS < 5
+5. Check budget pacing - are any campaigns limited?
+6. For shopping campaigns, check for product disapprovals
+7. Analyze device performance - any major mobile vs desktop differences?
+8. Summarize top 3 opportunities and top 3 concerns
+
+Keep the analysis actionable and prioritized by impact.
+
+To complete this review:
+- Use get_performance with level=campaign for current and prior period
+- Use search_terms_report and find_wasted_spend to identify waste
+- Use quality_score_analysis with max_quality_score=5 to find QS issues
+- Use budget_pacing to check for limited campaigns
+- Use shopping_product_status to check feed health
+- Use performance_by_dimension with dimension=device for device analysis`,
+    requiredTools: ['get_performance', 'search_terms_report', 'find_wasted_spend', 'quality_score_analysis', 'budget_pacing', 'shopping_product_status', 'performance_by_dimension']
+  },
+
+  negative_keyword_mining: {
+    name: 'negative_keyword_mining',
+    description: 'Find and add negative keywords from search terms data',
+    arguments: [
+      {
+        name: 'customer_id',
+        description: 'Google Ads account ID (without dashes)',
+        required: true
+      },
+      {
+        name: 'date_range',
+        description: 'Date range to analyze',
+        required: false,
+        default: 'LAST_30_DAYS'
+      },
+      {
+        name: 'min_spend',
+        description: 'Minimum spend threshold in dollars',
+        required: false,
+        default: '20'
+      }
+    ],
+    template: `Analyze search terms for {{customer_id}} over the last {{date_range}}:
+
+1. Pull search terms with spend > \${{min_spend}} and 0 conversions
+2. Group them into themes (irrelevant intent, competitor, informational, etc.)
+3. Recommend specific negative keywords with appropriate match types
+4. Flag any search terms that might be worth adding as keywords instead
+5. After I approve, add the negatives at the appropriate level (campaign vs ad group)
+
+Be aggressive on clear waste, conservative on ambiguous terms.`,
+    requiredTools: ['search_terms_report', 'find_wasted_spend', 'add_negative_keywords']
+  },
+
+  shopping_optimization: {
+    name: 'shopping_optimization',
+    description: 'Shopping campaign deep-dive and optimization recommendations',
+    arguments: [
+      {
+        name: 'customer_id',
+        description: 'Google Ads account ID (without dashes)',
+        required: true
+      }
+    ],
+    template: `Deep-dive into Shopping performance for {{customer_id}}:
+
+1. Product-level performance - find winners (high ROAS) and losers (high spend, low return)
+2. Check product disapprovals and feed health
+3. Analyze by brand and category - where should we increase/decrease investment?
+4. Compare to last period - any products trending significantly up or down?
+5. Recommend bid adjustments for top 10 products to optimize
+6. Identify products with high impressions but low click-through (possible title/image issues)
+
+Focus on actionable changes with clear expected impact.
+
+To complete this analysis:
+- Use shopping_performance with segment_by=product_item_id for product-level data
+- Use shopping_performance with segment_by=brand for brand analysis
+- Use shopping_performance with segment_by=category_l1 for category analysis
+- Use shopping_product_status to check for disapprovals and feed issues
+- Use get_performance with level=campaign and campaign_types=SHOPPING for overall Shopping performance`,
+    requiredTools: ['shopping_performance', 'shopping_product_status', 'get_performance']
+  },
+
+  competitive_analysis: {
+    name: 'competitive_analysis',
+    description: 'Analyze positioning and performance patterns to identify competitive opportunities',
+    arguments: [
+      {
+        name: 'customer_id',
+        description: 'Google Ads account ID (without dashes)',
+        required: true
+      }
+    ],
+    template: `Run competitive positioning analysis for {{customer_id}}:
+
+1. Identify top campaigns by spend and analyze impression share metrics
+2. Analyze top-of-page and absolute top impression rates - where are we losing visibility?
+3. Cross-reference with Quality Score - is positioning a bid issue or quality issue?
+4. Check hour-of-day and day-of-week performance - are there time windows with better/worse performance?
+5. Analyze search impression share loss due to budget vs rank
+6. Recommend strategy adjustments based on performance gaps
+
+To complete this analysis:
+- Use get_performance with level=campaign including impression share metrics to identify positioning
+- Use quality_score_analysis to determine if positioning issues are quality-related vs bid-related
+- Use performance_by_dimension with dimension=hour_of_day for time-based patterns
+- Use performance_by_dimension with dimension=day_of_week for day-based patterns`,
+    requiredTools: ['quality_score_analysis', 'performance_by_dimension', 'get_performance']
+  }
+};
+
+/**
+ * Get prompt definition by name
+ * @param {string} name - Prompt name
+ * @returns {Object|null} Prompt definition or null if not found
+ */
+export function getPromptDefinition(name) {
+  return PROMPT_TEMPLATES[name] || null;
+}
+
+/**
+ * Render a prompt template with provided arguments
+ * @param {string} name - Prompt name
+ * @param {Object} args - Arguments to substitute
+ * @returns {Object} Rendered prompt with messages array
+ */
+export function renderPrompt(name, args = {}) {
+  const promptDef = PROMPT_TEMPLATES[name];
+
+  if (!promptDef) {
+    throw new Error(`Unknown prompt: ${name}. Available prompts: ${Object.keys(PROMPT_TEMPLATES).join(', ')}`);
+  }
+
+  // Check required arguments
+  const missingArgs = promptDef.arguments
+    .filter(arg => arg.required && !args[arg.name])
+    .map(arg => arg.name);
+
+  if (missingArgs.length > 0) {
+    throw new Error(`Missing required arguments for prompt "${name}": ${missingArgs.join(', ')}`);
+  }
+
+  // Start with template
+  let rendered = promptDef.template;
+
+  // Substitute provided arguments
+  for (const [key, value] of Object.entries(args)) {
+    rendered = rendered.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+  }
+
+  // Apply defaults for remaining placeholders
+  promptDef.arguments.forEach(arg => {
+    if (arg.default !== undefined) {
+      rendered = rendered.replace(new RegExp(`\\{\\{${arg.name}\\}\\}`, 'g'), arg.default);
+    }
+  });
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: rendered
+        }
+      }
+    ]
+  };
+}
+
+/**
+ * Get all available prompts for listing
+ * @returns {Array} Array of prompt definitions for MCP
+ */
+export function getPromptsList() {
+  return Object.values(PROMPT_TEMPLATES).map(prompt => ({
+    name: prompt.name,
+    description: prompt.description,
+    arguments: prompt.arguments
+  }));
+}

package/server/resources/index.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Resource definitions for MCP
+ */
+export const RESOURCES = [
+  {
+    uri: 'gaql://reference',
+    name: 'GAQL Reference',
+    description: 'Google Ads Query Language syntax reference with examples',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'metrics://definitions',
+    name: 'Metrics Glossary',
+    description: 'Google Ads metrics definitions and calculations',
+    mimeType: 'text/markdown'
+  }
+];
+
+/**
+ * Read a resource by URI
+ * @param {string} uri - Resource URI
+ * @returns {Object} Resource content
+ */
+export function readResource(uri) {
+  const resourceMap = {
+    'gaql://reference': 'gaql-reference.md',
+    'metrics://definitions': 'metrics-glossary.md'
+  };
+
+  const filename = resourceMap[uri];
+  if (!filename) {
+    throw new Error(`Unknown resource: ${uri}. Available: ${Object.keys(resourceMap).join(', ')}`);
+  }
+
+  const filePath = join(__dirname, filename);
+
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+
+    return {
+      contents: [
+        {
+          uri: uri,
+          mimeType: 'text/markdown',
+          text: content
+        }
+      ]
+    };
+  } catch (error) {
+    throw new Error(`Failed to read resource ${uri}: ${error.message}`);
+  }
+}
+
+/**
+ * Get list of available resources
+ * @returns {Array} Resource definitions
+ */
+export function getResourcesList() {
+  return RESOURCES;
+}

package/server/tools/gaql-query.js

@@ -0,0 +1,141 @@
+import { getCustomerClient } from '../auth.js';
+import { formatSuccess, formatError } from '../utils/response-format.js';
+import { blockMutations } from '../utils/validation.js';
+
+/**
+ * Execute raw GAQL queries for advanced users
+ * Provides escape hatch for custom queries with safety guards
+ *
+ * @param {Object} params
+ * @param {string} [params.customer_id] - Google Ads account ID
+ * @param {string} params.query - GAQL query string (SELECT only)
+ * @param {number} [params.limit=100] - Maximum rows to return (max: 10000)
+ * @returns {Object} MCP response with query results
+ */
+export async function runGaqlQuery(params = {}) {
+  try {
+    // Validate required parameters
+    if (!params.query || typeof params.query !== 'string') {
+      throw new Error('query parameter is required and must be a string');
+    }
+
+    const query = params.query.trim();
+
+    // Validate query is not empty
+    if (!query) {
+      throw new Error('query cannot be empty');
+    }
+
+    // Block mutation operations for safety
+    blockMutations(query);
+
+    // Validate query starts with SELECT
+    if (!query.toUpperCase().startsWith('SELECT')) {
+      throw new Error(
+        'Query must start with SELECT. This tool only supports read operations. ' +
+        'Use the mutate tool for write operations.'
+      );
+    }
+
+    // Get customer ID
+    const customerId = params.customer_id || process.env.GOOGLE_ADS_DEFAULT_CUSTOMER_ID;
+    if (!customerId) {
+      throw new Error('customer_id parameter or GOOGLE_ADS_DEFAULT_CUSTOMER_ID environment variable required');
+    }
+
+    // Validate and enforce limit
+    const requestedLimit = params.limit || 100;
+    const maxLimit = 10000;
+    const limit = Math.min(Math.max(1, requestedLimit), maxLimit);
+
+    // Check if query already has LIMIT clause
+    const hasLimit = /\bLIMIT\s+\d+/i.test(query);
+
+    // Build final query with enforced limit
+    let finalQuery = query;
+    if (!hasLimit) {
+      finalQuery = `${query} LIMIT ${limit}`;
+    } else {
+      // Extract existing limit and enforce max
+      const existingLimit = parseInt(query.match(/\bLIMIT\s+(\d+)/i)[1], 10);
+      if (existingLimit > maxLimit) {
+        finalQuery = query.replace(/\bLIMIT\s+\d+/i, `LIMIT ${maxLimit}`);
+      }
+    }
+
+    const customer = getCustomerClient(customerId);
+
+    // Execute query
+    const startTime = Date.now();
+    const results = await customer.query(finalQuery);
+    const executionTime = Date.now() - startTime;
+
+    // Process results
+    const rowCount = results.length;
+
+    // Flatten results for readability
+    const data = results.map(row => flattenRow(row));
+
+    // Extract field names from first row
+    const fields = data.length > 0 ? Object.keys(data[0]) : [];
+
+    return formatSuccess({
+      summary: `Query returned ${rowCount} row${rowCount !== 1 ? 's' : ''} in ${executionTime}ms`,
+      data: {
+        rows: data,
+        fields: fields
+      },
+      metadata: {
+        customer_id: customerId,
+        row_count: rowCount,
+        field_count: fields.length,
+        execution_time_ms: executionTime,
+        limit_applied: limit,
+        query_truncated: rowCount >= limit,
+        query_preview: finalQuery.length > 200
+          ? finalQuery.substring(0, 200) + '...'
+          : finalQuery
+      }
+    });
+
+  } catch (error) {
+    return formatError(error);
+  }
+}
+
+/**
+ * Flatten a nested result row into a flat object
+ * Converts nested structures like { campaign: { id: '123' } } to { 'campaign.id': '123' }
+ *
+ * @param {Object} row - Query result row
+ * @param {string} [prefix=''] - Key prefix for nested objects
+ * @returns {Object} Flattened row
+ */
+function flattenRow(row, prefix = '') {
+  const result = {};
+
+  for (const [key, value] of Object.entries(row)) {
+    const newKey = prefix ? `${prefix}.${key}` : key;
+
+    if (value === null || value === undefined) {
+      result[newKey] = null;
+    } else if (typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively flatten nested objects
+      Object.assign(result, flattenRow(value, newKey));
+    } else if (Array.isArray(value)) {
+      // Keep arrays as-is but stringify for readability
+      result[newKey] = value;
+    } else {
+      // Handle micros conversion for common fields
+      if (key.endsWith('_micros') && typeof value === 'number') {
+        const baseKey = newKey.replace('_micros', '');
+        result[baseKey] = value / 1000000;
+        result[newKey] = value; // Keep original for precision
+      } else {
+        result[newKey] = value;
+      }
+    }
+  }
+
+  return result;
+}

package/server/tools/list-accounts.js

@@ -0,0 +1,61 @@
+import { getCustomerClient } from '../auth.js';
+import { formatSuccess, formatError } from '../utils/response-format.js';
+import { buildQuery, TEMPLATES } from '../utils/gaql-templates.js';
+
+/**
+ * List all accessible Google Ads accounts
+ * @param {Object} params
+ * @param {boolean} [params.include_manager_accounts=false] - Include MCC accounts
+ * @returns {Object} MCP response with account list
+ */
+export async function listAccounts(params = {}) {
+  try {
+    const includeManagers = params.include_manager_accounts || false;
+
+    // Use login customer ID or default customer ID
+    const customerId = process.env.GOOGLE_ADS_LOGIN_CUSTOMER_ID ||
+                       process.env.GOOGLE_ADS_DEFAULT_CUSTOMER_ID;
+
+    if (!customerId) {
+      throw new Error(
+        'Either GOOGLE_ADS_LOGIN_CUSTOMER_ID or GOOGLE_ADS_DEFAULT_CUSTOMER_ID must be set'
+      );
+    }
+
+    // Get customer client
+    const customer = getCustomerClient(customerId);
+
+    // Build query with optional manager filter
+    const filters = includeManagers ? '' : "WHERE customer_client.manager = false";
+    const query = buildQuery(TEMPLATES.LIST_ACCOUNTS, { filters });
+
+    // Execute query
+    const results = await customer.query(query);
+
+    // Format results
+    const accounts = results.map(row => ({
+      id: row.customer_client.id,
+      name: row.customer_client.descriptive_name,
+      is_manager: row.customer_client.manager,
+      currency: row.customer_client.currency_code,
+      timezone: row.customer_client.time_zone,
+      status: row.customer_client.status
+    }));
+
+    const managerCount = accounts.filter(a => a.is_manager).length;
+    const clientCount = accounts.length - managerCount;
+
+    return formatSuccess({
+      summary: `Found ${accounts.length} accessible account${accounts.length !== 1 ? 's' : ''} (${clientCount} client, ${managerCount} manager)`,
+      data: accounts,
+      metadata: {
+        totalAccounts: accounts.length,
+        clientAccounts: clientCount,
+        managerAccounts: managerCount
+      }
+    });
+
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/mutate.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { getCustomerClient } from '../auth.js';
+
+/**
+ * Execute mutation operations using GoogleAdsService.Mutate
+ * Supports any write operation with dry_run validation
+ *
+ * @param {Object} params - Mutation parameters
+ * @param {string} params.customer_id - Google Ads customer ID (optional, uses env default)
+ * @param {Array} params.operations - Array of mutation operation objects
+ * @param {boolean} params.partial_failure - Enable partial failure mode (default: true)
+ * @param {boolean} params.dry_run - Validate only, don't execute (default: true)
+ * @returns {Promise<Object>} Mutation results
+ */
+export async function mutate(params) {
+  const {
+    customer_id = process.env.GOOGLE_ADS_CUSTOMER_ID,
+    operations,
+    partial_failure = true,
+    dry_run = true
+  } = params;
+
+  // Validate required parameters
+  if (!customer_id) {
+    return {
+      success: false,
+      error: 'customer_id is required (either as parameter or GOOGLE_ADS_CUSTOMER_ID env var)'
+    };
+  }
+
+  if (!operations || !Array.isArray(operations) || operations.length === 0) {
+    return {
+      success: false,
+      error: 'operations array is required and must contain at least one operation'
+    };
+  }
+
+  try {
+    const customer = getCustomerClient(customer_id);
+
+    // Execute mutation with validation options
+    const response = await customer.mutateResources(operations, {
+      partialFailure: partial_failure,
+      validateOnly: dry_run
+    });
+
+    return {
+      success: true,
+      dry_run,
+      results: response,
+      message: dry_run
+        ? 'Validation successful - no changes made'
+        : 'Mutations applied successfully',
+      operations_count: operations.length
+    };
+  } catch (error) {
+    return {
+      success: false,
+      dry_run,
+      error: error.message,
+      error_details: error.errors || null
+    };
+  }
+}