gads_run_gaql
Run raw GAQL queries to fetch Google Ads data when preset tools lack the required report shape, enabling custom campaign and metric analysis.
Instructions
Escape hatch: run any raw GAQL query against Google Ads. Use when preset tools don't cover the report shape you need. Docs: developers.google.com/google-ads/api/docs/query/overview
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Raw GAQL query. Example: SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50 | |
| customer_id | No | Override GOOGLE_ADS_CUSTOMER_ID for this call (no dashes) |
Implementation Reference
- src/tools/gaql.ts:11-15 (handler)The core handler function that executes the GAQL query using the Google Ads client and returns rows.
export async function runGaql(args: z.infer<z.ZodObject<typeof runGaqlSchema>>) { const customer = getCustomer(args.customer_id); const rows = await customer.query(args.query); return { rowCount: rows.length, rows }; } - src/tools/gaql.ts:4-9 (schema)Zod schema defining the input parameters: 'query' (required string) and 'customer_id' (optional string override).
export const runGaqlSchema = { query: z.string().describe( "Raw GAQL query. Example: SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50" ), customer_id: z.string().optional().describe("Override GOOGLE_ADS_CUSTOMER_ID for this call (no dashes)"), }; - src/index.ts:57-62 (registration)Registration of the 'gads_run_gaql' tool on the MCP server with description, schema, and handler callback.
server.tool( "gads_run_gaql", "Escape hatch: run any raw GAQL query against Google Ads. Use when preset tools don't cover the report shape you need. Docs: developers.google.com/google-ads/api/docs/query/overview", runGaqlSchema, async (args) => { try { return ok(await runGaql(args)); } catch (e) { return err(e); } } ); - src/tools/gaql.ts:1-3 (helper)Imports: zod for validation and getCustomer helper from client to create the Google Ads service.
import { z } from "zod"; import { getCustomer } from "../client.js";