MCP

Google Ads MCPTool documentation

7 tool calls, their inputs and the limits of this connection. Implementation snapshot: 8 October 2026.

The complete tool reference.

5 read tools and 2 write tools. Open a tool to see its parameters and full JSON Schema. Unknown fields are rejected.

ads_list_customersList selected customers

Read

List only customers selected for this grant. No arbitrary MCC login context can be supplied.

Input parameters

No parameters. Pass an empty object: {}.

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

ads_get_customerGet customer

Read

Read the selected Ads customer ID, name, currency, timezone and test/manager flags.

Input parameters

resource_keyRequired: string · Max. characters: 100

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    }
  },
  "required": [
    "resource_key"
  ],
  "additionalProperties": false
}

ads_list_campaignsList campaigns

Read

Read campaigns and their current status, with a bounded row limit.

Input parameters

resource_keyRequired: string · Max. characters: 100
limitOptional: integer · Default: 1000 · min. 1 · max. 10000

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    },
    "limit": {
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "resource_key"
  ],
  "additionalProperties": false
}

ads_query_campaign_performanceRead campaign performance

Read

Read daily clicks, impressions, cost and conversions over at most 31 days. No arbitrary GAQL or auto-pagination.

Cache: 60 seconds.

Input parameters

resource_keyRequired: string · Max. characters: 100
start_dateRequired: string · date
end_dateRequired: string · date
limitOptional: integer · Default: 1000 · min. 1 · max. 10000

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "limit": {
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "resource_key",
    "start_date",
    "end_date"
  ],
  "additionalProperties": false
}

ads_list_labelsList labels

Read

Read existing labels for the selected customer.

Input parameters

resource_keyRequired: string · Max. characters: 100
limitOptional: integer · Default: 1000 · min. 1 · max. 10000

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    },
    "limit": {
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "resource_key"
  ],
  "additionalProperties": false
}

ads_create_labelCreate label

Write

Create a customer label. validate_only defaults true and checks Google validation without changing data. A real create needs validate_only=false and a new operation_id.

Input parameters

resource_keyRequired: string · Max. characters: 100
operation_idRequired: string · uuid
nameRequired: string · Min. characters: 1 · Max. characters: 80
descriptionOptional: string · Max. characters: 2000
background_colorOptional: string
validate_onlyOptional: boolean · Default: true

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    },
    "operation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique operation ID. Reuse only to retrieve this exact operation status; never reuse for changed arguments."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "maxLength": 2000
    },
    "background_color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$"
    },
    "validate_only": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "resource_key",
    "operation_id",
    "name"
  ],
  "additionalProperties": false
}

ads_set_campaign_statusPause or enable campaign

Write

Set one existing campaign to PAUSED or ENABLED. Enabling may resume ad spend. Requires explicit user intent. validate_only defaults true; a real change needs false and a new operation_id. Does not change budgets.

Changes existing configuration or campaign status. Requires explicit user intent.

Input parameters

resource_keyRequired: string · Max. characters: 100
operation_idRequired: string · uuid
campaign_idRequired: string · Max. characters: 40
statusRequired: string · PAUSED | ENABLED
validate_onlyOptional: boolean · Default: true

Full input schema (JSON)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_key": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^customers\\/[1-9]\\d*$"
    },
    "operation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique operation ID. Reuse only to retrieve this exact operation status; never reuse for changed arguments."
    },
    "campaign_id": {
      "type": "string",
      "maxLength": 40,
      "pattern": "^[1-9]\\d*$"
    },
    "status": {
      "type": "string",
      "enum": [
        "PAUSED",
        "ENABLED"
      ]
    },
    "validate_only": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "resource_key",
    "operation_id",
    "campaign_id",
    "status"
  ],
  "additionalProperties": false
}

A concrete tool call.

JSON-RPC request after MCP initialization. Sample IDs and dates: replace them with your selected resource and reporting period. The AI client handles transport and authorization.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ads_query_campaign_performance",
    "arguments": {
      "resource_key": "customers/1234567890",
      "start_date": "2026-09-01",
      "end_date": "2026-09-07",
      "limit": 100
    }
  }
}

How results come back.

structuredContent: Contains the tool result as a JSON object. Google field names are retained. The same JSON is also returned as a text block in content.
Data by tool: Read queries return Google's results with customer, campaign, metrics or label fields. costMicros is in millionths of the account currency. validate_only returns status: validated and validate_only: true without changing data.
Selected resources: The first list tool returns resources containing resource_key. It lists only resources authorized for this connection.
isError: true: Tool failures return structuredContent.error and request_id, optionally retry_after_seconds. For example: scope_missing for missing access or service_unavailable when a service cannot be reached. Do not repeat an uncertain write blindly.

Access and technical limits.

Performance queries: at most 31 inclusive days and 10,000 rows, default limit 1,000. Results may be cached for 60 seconds. No arbitrary GAQL, budget or bid changes. Both write tools default validate_only to true: a real write needs false and a new operation_id. ENABLED can resume ad spend.

Connection uses MCP Streamable HTTP with bearer authorization. The server checks read/write scope and the selected resource for each call. Both your Google permissions and MCP connection permissions must allow the operation. Clients discover tools using tools/list; these pages document the tool registry.

Read scope: mcp:ads:read. Write scope: mcp:ads:write.

Every write requires a UUID operation_id. Reuse it only for the exact same operation, never with changed arguments. A completed replay reports mutation_status: succeeded and replayed: true, optionally result_ref, rather than the original Google response. Writes are not retried automatically.