Google Ads MCP Server

Instructions

Implementation Reference

• src/tools/gaqlHelp.ts:51-122 (handler)

  Core handler function for the gaql_help tool. Handles input with topic or search, reads local MD files for specific topics, generates default overview with tips and links to official Google Ads API documentation.
  export async function gaqlHelp(input: GaqlHelpInput = {}): Promise<string> { const sections: string[] = []; const version = getApiVersion(); // If specific topic requested, return just that topic if (input.topic) { const topicContent = await readSpecificTopic(input.topic); if (topicContent) { sections.push(`# GAQL Help: ${input.topic.replace('-', ' ').toUpperCase()}`); sections.push(`**API Version**: ${version}\n`); sections.push(topicContent); // Add relevant official documentation link const officialUrl = OFFICIAL_URLS[input.topic.replace('-', '_') as keyof typeof OFFICIAL_URLS]; if (officialUrl) { sections.push(`\n**Official Documentation**: ${officialUrl}`); } sections.push(`\n**Field References**: ${getFieldReferenceUrls().join(', ')}`); return sections.join('\n'); } else { return `Topic "${input.topic}" not found. Available topics: ${AVAILABLE_TOPICS.join(', ')}`; } } // Default: Show overview with available topics sections.push('# Google Ads Query Language (GAQL) Help'); // Show available topics sections.push(` ## Available Topics Use the topic parameter to get specific documentation: ${AVAILABLE_TOPICS.map(topic => `- **${topic}**: ${topic.replace('-', ' ')} documentation`).join('\n')} Example: Use topic="overview" for basic GAQL concepts`); // Quick Tips sections.push(` ## Quick Tips - FROM uses a RESOURCE (use list_resources tool to discover available resources) - SELECT fields must be selectable for the chosen FROM resource - WHERE supports =, !=, <, >, >=, <=, LIKE, IN, DURING (for date ranges) - Date ranges: DURING LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, etc. - ORDER BY field [ASC|DESC], LIMIT n for sorting and limiting results - Case sensitivity: field names are case-insensitive; string values are case-sensitive - Cost fields are in micros - divide by 1,000,000 for actual currency amounts - Use customer.currency_code to interpret cost_micros correctly`); // API Version Info sections.push(` ## Current API Version: ${version} The MCP server is configured to use API version ${version}. Set GOOGLE_ADS_API_VERSION environment variable to use a different version.`); // Official Documentation Links sections.push(` ## Official Documentation ${Object.entries(OFFICIAL_URLS).map(([topic, url]) => `- ${topic.replace('_', ' ')}: ${url}`).join('\n')} ## Field References ${getFieldReferenceUrls().join('\n')}`); // Footer sections.push(` ## Need More Help? - Use topic parameter to get detailed documentation on specific areas - Use the "list_resources" tool to discover available resources and their fields - Use the "execute_gaql_query" tool to test your queries - Check field compatibility in the official API reference above`); return sections.join('\n'); }
• src/schemas.ts:69-73 (schema)

  Zod schema GaqlHelpZ and derived JSON schema for input validation of the gaql_help tool.
  export const GaqlHelpZ = z.object({ topic: z.enum(['overview', 'grammar', 'structure', 'date-ranges', 'case-sensitivity', 'ordering-limiting', 'cookbook', 'field-reference']).optional().describe('specific GAQL topic to retrieve'), search: z.string().optional().describe('search term for help content'), }); export const GaqlHelpSchema: JsonSchema = zodToJsonSchema(GaqlHelpZ, 'GaqlHelp') as unknown as JsonSchema;
• src/server-tools.ts:721-745 (registration)

  MCP tool registration for 'gaql_help', including name, description, schema, and wrapper handler that invokes the core gaqlHelp function.
  server, "gaql_help", "Get GAQL help with local documentation and official Google Ads API links. Use topic for specific areas or search for keywords.", GaqlHelpZ, async (input: any) => { const startTs = Date.now(); try { const text = await gaqlHelp({ topic: input?.topic, search: input?.search, }); const out = { content: [{ type: 'text', text }] }; logEvent('gaql_help', startTs, { requestId: input?.request_id }); return out; } catch (e: any) { const lines = [ `Error fetching GAQL help: ${e?.message || String(e)}`, 'Hint: set quick_tips=true to avoid network usage.', ]; const out = { content: [{ type: 'text', text: lines.join('\n') }] }; logEvent('gaql_help', startTs, { requestId: input?.request_id, error: { code: 'ERR_HELP', message: String(e?.message || e) } }); return out; } } );