Google Ads MCP Server

Instructions

Implementation Reference

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

  The primary handler function for the gaql_help tool. It provides GAQL documentation either for a specific topic from local markdown files or a default overview including quick tips, API version info, and links to official docs.
  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/server-tools.ts:721-746 (registration)

  The registration of the 'gaql_help' tool using addTool(server, name, description, schema, handler), where the handler wraps and calls the gaqlHelp function with logging.
  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; } } );
• src/schemas.ts:69-73 (schema)

  Zod schema (GaqlHelpZ) defining the input parameters for the gaql_help tool: optional topic (enum of GAQL topics) and search string.
  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;