Google Ads MCP Server Tool Reference
All tools below are mounted by default across five namespaces (customers,
search, metadata, labels, and assets).
Table of Contents
- Read Tools: Lines 12-52
- Partial Mutate Tools: Lines 53-136
- Read-Only Mode (
tools_config.yaml): Lines 137-150
Read Tools
1. customers_list_accessible_customers (list_accessible_customers)
- Purpose: Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.
- How to Use: Call first when starting a new session or when the target customer ID is unknown. Requires no arguments.
- Example Intent: "What Google Ads accounts do I have access to?"
2. metadata_get_resource_metadata (get_resource_metadata)
- Purpose: Retrieves selectable, filterable, and sortable GAQL fields,
metrics, and segments for a Google Ads API resource type (e.g.,
campaign,ad_group,customer). - Arguments:
resource_name(string, required): Resource name to inspect (e.g.,campaign).login_customer_id(string, optional): Manager account ID when accessing a client account via a manager.
- Example Intent: "What fields and metrics can I query for an ad group?"
3. search_search (search)
- Purpose: Builds and executes GAQL
SearchStreamqueries from structured parameters rather than a raw GAQL string. - Arguments:
customer_id(string, required): 10-digit target Google Ads customer ID (digits only, no hyphens).resource(string, required): Google Ads API resource name (e.g.,campaign).fields(list of strings, required): Selectable fields, metrics, and segments (e.g.,["campaign.id", "campaign.name", "campaign.status","metrics.impressions"]).conditions(list[str], optional) andorderings(list[str], optional): Structured filter and sort expressions.limit(int, optional) andlogin_customer_id(string, optional): Row limit and manager account ID.
- Example Intent: "Get the impressions and status of all enabled campaigns for account 1234567890."
Partial Mutate Tools
Mutate support covers standalone asset creation, local video uploads, and account/entity label management. The server cannot link assets to campaigns or ad groups, or create, modify, pause, or enable campaigns, ad groups, ads, budgets, or bids.
Propose-and-Confirm Safety Workflow
Every mutate tool enforces a two-step workflow:
- Propose (
validate_only=True, default): Validates inputs without committing changes (assets_upload_video_assetvalidates the local file and binds its size and modification timestamp) and returnschange_itemsplus a stateless SHA-256checksumbound tocustomer_idand payload. - Confirm (
validate_only=False): After user approval, call the tool again withvalidate_only=False, the identicalcustomer_idand arguments, and thechecksumfrom step 1.
4. assets_create_asset (create_asset)
- Purpose: Creates standalone Google Ads assets (
TEXT,IMAGE,YOUTUBE_VIDEO,SITELINK,CALLOUT,STRUCTURED_SNIPPET, or otherAssetServicetypes viaextra_params). - Key Arguments:
customer_id(string, required): 10-digit target Google Ads customer ID.asset_type(string, required): Asset type (e.g.,TEXT,IMAGE,YOUTUBE_VIDEO,SITELINK,CALLOUT,STRUCTURED_SNIPPET).- Type-specific fields:
text_asset_text(TEXT),callout_text(CALLOUT),structured_snippet_header+structured_snippet_values(STRUCTURED_SNIPPET),image_asset_path(local stdio only) or base64image_asset_data+image_asset_mime_type(IMAGE_PNG,IMAGE_JPEG,IMAGE_GIF, up to 20 MB),youtube_video_id, orsitelink_link_text+final_urls. validate_only(bool, optional, defaultTrue) andchecksum(string, required whenvalidate_only=False).
5. assets_upload_video_asset (upload_video_asset)
- Purpose: Uploads a local video file (
.3gp,.avi,.flv,.mkv,.mov,.mp4,.mpeg,.mpg,.ogg,.webm,.wmv) to YouTube via the Google Ads API (local stdio mode only). Returnsvideo_upload_id; pollyou_tube_video_uploadviasearch_searchuntilyou_tube_video_upload.state = 'PROCESSED', then passyou_tube_video_upload.video_idtoassets_create_asset. - Key Arguments:
customer_id(string, required): 10-digit target Google Ads customer ID.video_path(string, required): Local path to the video file.video_title(string, required) andvideo_description(string, required).video_privacy(string, optional),youtube_channel_id(string, optional), andlogin_customer_id(string, optional).validate_only(bool, optional, defaultTrue) andchecksum(string, required whenvalidate_only=False).
6. labels_manage_labels (manage_labels)
- Purpose: Creates, updates, and removes account labels (including name, description, and hex background color).
- Key Arguments:
customer_id(string, required): 10-digit target Google Ads customer ID.operation(string, required):CREATE,UPDATE, orREMOVE.name(string, required forCREATE) andlabel_id(string, required forUPDATEandREMOVE).background_color(string, optional),description(string, optional),login_customer_id(string, optional),validate_only(bool, optional, defaultTrue), andchecksum(string, required whenvalidate_only=False).
7. labels_manage_label_associations (manage_label_associations)
- Purpose: Creates or removes (
CREATE/REMOVE;UPDATEunsupported) label associations onCAMPAIGN,CUSTOMER,AD_GROUP, andAD_GROUP_CRITERIONresources (AD_GROUP_ADis unsupported). - Key Arguments:
customer_id(string, required): 10-digit target Google Ads customer ID.operation(string, required):CREATEorREMOVE.association_type(string, required):CAMPAIGN,CUSTOMER,AD_GROUP, orAD_GROUP_CRITERION.resource_id(optional forCUSTOMER, defaults tocustomer_id; composite{ad_group_id}~{criterion_id}forAD_GROUP_CRITERION),label_id(orassociation_resource_namefor removals),validate_only(bool, optional, defaultTrue), andchecksum(string, required whenvalidate_only=False).
Read-Only Mode (tools_config.yaml)
To enforce a strictly read-only deployment, set labels: false and
assets: false alongside enabled read namespaces in tools_config.yaml (or
point GOOGLE_ADS_MCP_TOOLS_CONFIG to that file):
namespaces:
customers: true
search: true
metadata: true
labels: false
assets: false