Google Ads MCP Server

Instructions

Implementation Reference

• src/server-tools.ts:517-637 (handler)

  Main handler for get_performance tool: manages sessions, builds and executes GAQL query for performance data at specified level (account/campaign/etc), handles pagination and formatting.
  async (_input: any) => { const input = (_input || {}) as any; const startTs = Date.now(); let sessionKey: string | undefined; try { sessionKey = requireSessionKeyIfEnabled(input); } catch (e: any) { const msg = e?.message || String(e); logEvent('get_performance', startTs, { sessionKey, customerId: input?.customer_id, requestId: input?.request_id, error: { code: 'ERR_INPUT', message: String(msg) } }); return { content: [{ type: 'text', text: `Error: ${msg}` }] }; } if (sessionKey) { const rc = checkRateLimit(sessionKey); if (!rc.allowed) { logEvent('get_performance', startTs, { sessionKey, customerId: input?.customer_id, requestId: input?.request_id, error: { code: 'ERR_RATE_LIMITED', message: `Retry after ${rc.retryAfter}s` } }); return { content: [{ type: 'text', text: JSON.stringify({ error: { code: 'ERR_RATE_LIMITED', message: `Rate limit exceeded. Retry after ${rc.retryAfter} seconds`, retry_after: rc.retryAfter } }) }] }; } } if (!input.customer_id) { const envAccount = process.env.GOOGLE_ADS_ACCOUNT_ID; if (envAccount) { input.customer_id = envAccount; } else { const res = await listAccessibleCustomers(sessionKey); if (!res.ok) { const hint = mapAdsErrorMsg(res.status, res.errorText || ''); const lines = [ 'No customer_id provided. Please choose an account and re-run with customer_id.', `Error listing accounts (status ${res.status}): ${res.errorText || ''}`, ]; if (hint) lines.push(`Hint: ${hint}`); logEvent('get_performance', startTs, { sessionKey, requestId: input?.request_id, error: { code: `HTTP_${res.status}`, message: String(res.errorText || '') } }); return { content: [{ type: 'text', text: lines.join('\n') }] }; } const names = res.data?.resourceNames || []; if (!names.length) return { content: [{ type: 'text', text: 'No accessible accounts found.' }] }; const rows = names.map((rn: string) => ({ account_id: (rn.split('/').pop() || rn) })); const table = tabulate(rows, ['account_id']); const lines = [ 'No customer_id provided. Select one of the accounts below, then call again with customer_id.', table, ]; logEvent('get_performance', startTs, { sessionKey, requestId: input?.request_id }); return { content: [{ type: 'text', text: lines.join('\n') }] }; } } // Enforce allowlist if present if (sessionKey && input.customer_id && !isCustomerAllowedForSession(sessionKey, input.customer_id)) { return { content: [{ type: 'text', text: `Error: Customer ID ${input.customer_id} not in allowlist for this session` }] }; } const days = Math.max(1, Math.min(365, Number(input.days ?? 30))); const limit = Math.max(1, Math.min(1000, Number(input.limit ?? 50))); const query = buildPerformanceQuery(input.level, days, limit, input.filters || {}); const auto = !!input.auto_paginate; const maxPages = Math.max(1, Math.min(20, Number(input.max_pages ?? 5))); const pageSize = (typeof input.page_size === 'number') ? Math.max(1, Math.min(10_000, Number(input.page_size))) : undefined; let pageToken = input.page_token as string | undefined; let all: any[] = []; let lastToken: string | undefined; let pageCount = 0; // Normalize MCC/login-customer aliases for robustness const loginCustomerId = (input as any).login_customer_id ?? (input as any).loginCustomerId ?? (input as any).managerAccountId ?? (input as any).mcc; do { const res = await executeGaql({ customerId: input.customer_id, query, pageSize, pageToken, loginCustomerId, sessionKey }); if (!res.ok) { const hint = mapAdsErrorMsg(res.status, res.errorText || ''); const lines = [`Error executing performance query (status ${res.status}): ${res.errorText || ''}`]; if (hint) lines.push(`Hint: ${hint}`); logEvent('get_performance', startTs, { sessionKey, customerId: input.customer_id, requestId: input?.request_id, error: { code: `HTTP_${res.status}`, message: String(res.errorText || '') } }); return { content: [{ type: "text", text: lines.join('\n') }] }; } const data = res.data; const results = (data?.results && Array.isArray(data.results)) ? data.results : []; all = all.concat(results); lastToken = data?.nextPageToken; pageToken = auto ? lastToken : undefined; pageCount++; } while (auto && pageToken && pageCount < maxPages); if (!all.length) { return { content: [{ type: "text", text: "No results found for the selected period." }] }; } const rows = (all as any[]).map((r: any) => { const out = { ...r }; const metrics = { ...(r?.metrics || {}) } as any; const micros = (metrics.cost_micros ?? metrics.costMicros); if (typeof micros === 'number') metrics.cost_units = microsToUnits(micros); (out as any).metrics = metrics; return out; }); const first = rows[0]; const fields: string[] = []; for (const key of Object.keys(first)) { const val = (first as any)[key]; if (val && typeof val === "object" && !Array.isArray(val)) { for (const sub of Object.keys(val)) fields.push(`${key}.${sub}`); } else { fields.push(key); } } const fmt = (input.output_format || 'table').toLowerCase(); if (fmt === 'json') return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] }; if (fmt === 'csv') { const { toCsv } = await import('./utils/formatCsv.js'); const csv = toCsv(rows, fields); return { content: [{ type: 'text', text: csv }] }; } const table = tabulate(rows, fields); const lines: string[] = [ `Performance (${input.level}) for last ${input.days ?? 30} days:`, table, ]; if (!auto && lastToken) lines.push(`Next Page Token: ${lastToken}`); if (auto) lines.push(`Pages fetched: ${pageCount}`); const out = { content: [{ type: "text", text: lines.join("\n") }] }; logEvent('get_performance', startTs, { sessionKey, customerId: input.customer_id, requestId: input?.request_id }); return out; }
• src/server-tools.ts:512-638 (registration)

  Registration of the get_performance tool using addTool, linking name, description, schema, and handler.
  addTool( server, "get_performance", "Get performance (level: account|campaign|ad_group|ad). Optional: login_customer_id (aka MCC/manager account id) overrides env.", GetPerformanceZ, async (_input: any) => { const input = (_input || {}) as any; const startTs = Date.now(); let sessionKey: string | undefined; try { sessionKey = requireSessionKeyIfEnabled(input); } catch (e: any) { const msg = e?.message || String(e); logEvent('get_performance', startTs, { sessionKey, customerId: input?.customer_id, requestId: input?.request_id, error: { code: 'ERR_INPUT', message: String(msg) } }); return { content: [{ type: 'text', text: `Error: ${msg}` }] }; } if (sessionKey) { const rc = checkRateLimit(sessionKey); if (!rc.allowed) { logEvent('get_performance', startTs, { sessionKey, customerId: input?.customer_id, requestId: input?.request_id, error: { code: 'ERR_RATE_LIMITED', message: `Retry after ${rc.retryAfter}s` } }); return { content: [{ type: 'text', text: JSON.stringify({ error: { code: 'ERR_RATE_LIMITED', message: `Rate limit exceeded. Retry after ${rc.retryAfter} seconds`, retry_after: rc.retryAfter } }) }] }; } } if (!input.customer_id) { const envAccount = process.env.GOOGLE_ADS_ACCOUNT_ID; if (envAccount) { input.customer_id = envAccount; } else { const res = await listAccessibleCustomers(sessionKey); if (!res.ok) { const hint = mapAdsErrorMsg(res.status, res.errorText || ''); const lines = [ 'No customer_id provided. Please choose an account and re-run with customer_id.', `Error listing accounts (status ${res.status}): ${res.errorText || ''}`, ]; if (hint) lines.push(`Hint: ${hint}`); logEvent('get_performance', startTs, { sessionKey, requestId: input?.request_id, error: { code: `HTTP_${res.status}`, message: String(res.errorText || '') } }); return { content: [{ type: 'text', text: lines.join('\n') }] }; } const names = res.data?.resourceNames || []; if (!names.length) return { content: [{ type: 'text', text: 'No accessible accounts found.' }] }; const rows = names.map((rn: string) => ({ account_id: (rn.split('/').pop() || rn) })); const table = tabulate(rows, ['account_id']); const lines = [ 'No customer_id provided. Select one of the accounts below, then call again with customer_id.', table, ]; logEvent('get_performance', startTs, { sessionKey, requestId: input?.request_id }); return { content: [{ type: 'text', text: lines.join('\n') }] }; } } // Enforce allowlist if present if (sessionKey && input.customer_id && !isCustomerAllowedForSession(sessionKey, input.customer_id)) { return { content: [{ type: 'text', text: `Error: Customer ID ${input.customer_id} not in allowlist for this session` }] }; } const days = Math.max(1, Math.min(365, Number(input.days ?? 30))); const limit = Math.max(1, Math.min(1000, Number(input.limit ?? 50))); const query = buildPerformanceQuery(input.level, days, limit, input.filters || {}); const auto = !!input.auto_paginate; const maxPages = Math.max(1, Math.min(20, Number(input.max_pages ?? 5))); const pageSize = (typeof input.page_size === 'number') ? Math.max(1, Math.min(10_000, Number(input.page_size))) : undefined; let pageToken = input.page_token as string | undefined; let all: any[] = []; let lastToken: string | undefined; let pageCount = 0; // Normalize MCC/login-customer aliases for robustness const loginCustomerId = (input as any).login_customer_id ?? (input as any).loginCustomerId ?? (input as any).managerAccountId ?? (input as any).mcc; do { const res = await executeGaql({ customerId: input.customer_id, query, pageSize, pageToken, loginCustomerId, sessionKey }); if (!res.ok) { const hint = mapAdsErrorMsg(res.status, res.errorText || ''); const lines = [`Error executing performance query (status ${res.status}): ${res.errorText || ''}`]; if (hint) lines.push(`Hint: ${hint}`); logEvent('get_performance', startTs, { sessionKey, customerId: input.customer_id, requestId: input?.request_id, error: { code: `HTTP_${res.status}`, message: String(res.errorText || '') } }); return { content: [{ type: "text", text: lines.join('\n') }] }; } const data = res.data; const results = (data?.results && Array.isArray(data.results)) ? data.results : []; all = all.concat(results); lastToken = data?.nextPageToken; pageToken = auto ? lastToken : undefined; pageCount++; } while (auto && pageToken && pageCount < maxPages); if (!all.length) { return { content: [{ type: "text", text: "No results found for the selected period." }] }; } const rows = (all as any[]).map((r: any) => { const out = { ...r }; const metrics = { ...(r?.metrics || {}) } as any; const micros = (metrics.cost_micros ?? metrics.costMicros); if (typeof micros === 'number') metrics.cost_units = microsToUnits(micros); (out as any).metrics = metrics; return out; }); const first = rows[0]; const fields: string[] = []; for (const key of Object.keys(first)) { const val = (first as any)[key]; if (val && typeof val === "object" && !Array.isArray(val)) { for (const sub of Object.keys(val)) fields.push(`${key}.${sub}`); } else { fields.push(key); } } const fmt = (input.output_format || 'table').toLowerCase(); if (fmt === 'json') return { content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }] }; if (fmt === 'csv') { const { toCsv } = await import('./utils/formatCsv.js'); const csv = toCsv(rows, fields); return { content: [{ type: 'text', text: csv }] }; } const table = tabulate(rows, fields); const lines: string[] = [ `Performance (${input.level}) for last ${input.days ?? 30} days:`, table, ]; if (!auto && lastToken) lines.push(`Next Page Token: ${lastToken}`); if (auto) lines.push(`Pages fetched: ${pageCount}`); const out = { content: [{ type: "text", text: lines.join("\n") }] }; logEvent('get_performance', startTs, { sessionKey, customerId: input.customer_id, requestId: input?.request_id }); return out; } );
• src/schemas.ts:45-66 (schema)

  Zod schema definition for get_performance input validation (GetPerformanceZ) and JSON schema export.
  export const GetPerformanceZ = z.object({ customer_id: z.string().optional().describe('10-digit customer ID (no dashes). Optional.'), // Per-call login customer (MCC/manager) override login_customer_id: z.union([z.string(), z.number()]).optional().describe('Manager account (MCC) ID to use as login-customer for this request (10 digits, no dashes). Overrides env GOOGLE_ADS_MANAGER_ACCOUNT_ID.'), level: z.enum(['account','campaign','ad_group','ad']).describe('Aggregation level'), days: z.number().default(30).describe('Days back to query (1-365, default 30)'), limit: z.number().default(50).describe('GAQL LIMIT (1-1000, default 50)'), page_size: z.number().min(1).optional().describe('optional page size (1-10000)'), page_token: z.string().optional().describe('optional page token'), auto_paginate: z.boolean().default(false).describe('fetch multiple pages automatically'), max_pages: z.number().min(1).max(20).default(5).describe('limit when auto_paginate=true (1-20)'), output_format: z.enum(['table','json','csv']).default('table').describe('render format'), filters: z.object({ status: z.string().optional().describe('e.g., ENABLED, PAUSED'), name_contains: z.string().optional().describe('substring in entity name (case sensitive)'), campaign_name_contains: z.string().optional().describe('substring in campaign name (case sensitive)'), min_clicks: z.number().optional().describe('minimum clicks (>=0)'), min_impressions: z.number().optional().describe('minimum impressions (>=0)'), }).optional().describe('optional performance filters'), }); export const GetPerformanceSchema: JsonSchema = zodToJsonSchema(GetPerformanceZ, 'GetPerformance') as unknown as JsonSchema;
• src/tools/performance.ts:11-106 (helper)

  Helper function buildPerformanceQuery generates the GAQL query string tailored to the performance level, date range, limits, and filters.
  export function buildPerformanceQuery( level: PerformanceLevel, days = 30, limit = 50, filters: PerformanceFilters = {} ): string { // Runtime bounds const safeDays = Math.max(1, Math.min(365, Math.floor(days))); const safeLimit = Math.max(1, Math.min(1000, Math.floor(limit))); const baseMetrics = ` metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.average_cpc, customer.currency_code `; let fields = ''; let from = ''; let statusField = ''; let nameField = ''; const campaignNameField = 'campaign.name'; switch (level) { case 'account': fields = ` customer.id, customer.descriptive_name, customer.currency_code, ${baseMetrics} `; from = 'customer'; statusField = 'customer.status'; nameField = 'customer.descriptive_name'; break; case 'campaign': fields = ` campaign.id, campaign.name, campaign.status, ${baseMetrics} `; from = 'campaign'; statusField = 'campaign.status'; nameField = 'campaign.name'; break; case 'ad_group': fields = ` campaign.name, ad_group.id, ad_group.name, ad_group.status, ${baseMetrics} `; from = 'ad_group'; statusField = 'ad_group.status'; nameField = 'ad_group.name'; break; case 'ad': fields = ` campaign.name, ad_group.name, ad_group_ad.ad.id, ad_group_ad.status, ${baseMetrics} `; from = 'ad_group_ad'; statusField = 'ad_group_ad.status'; nameField = 'ad_group.name'; break; default: throw new Error('Invalid level. Use campaign | ad_group | ad'); } const whereClauses: string[] = [` SELECT ${fields} FROM ${from} WHERE segments.date DURING LAST_${safeDays}_DAYS`]; // Apply filters const esc = (v: string) => v.replace(/'/g, "''"); if (filters.status) whereClauses.push(`AND ${statusField} = '${esc(filters.status)}'`); if (filters.name_contains) whereClauses.push(`AND ${nameField} LIKE '%${esc(filters.name_contains)}%'`); if (filters.campaign_name_contains && level !== 'account') whereClauses.push(`AND ${campaignNameField} LIKE '%${esc(filters.campaign_name_contains)}%'`); if (typeof filters.min_clicks === 'number') whereClauses.push(`AND metrics.clicks >= ${Math.max(0, Math.floor(filters.min_clicks))}`); if (typeof filters.min_impressions === 'number') whereClauses.push(`AND metrics.impressions >= ${Math.max(0, Math.floor(filters.min_impressions))}`); const query = ` ${whereClauses.join('\n ')} ORDER BY metrics.cost_micros DESC LIMIT ${safeLimit} `; return query; }