Google Ads

In the Google Cloud Console, go to APIs & Services → Library. Search for Google Ads API and click Enable. Make sure you enable it on the same Google Cloud project that your GA4 / GSC OAuth client lives on — ShopMCP reuses the same OAuth credentials across all Google modules.

In the Google Cloud Console, go to APIs & Services → OAuth consent screen → Scopes. Click Add or Remove Scopes and add:

• https://www.googleapis.com/auth/adwords — this is the only scope required for Google Ads API access

Save the consent screen. If your app is still in Testing mode, make sure the Google account you plan to connect is listed as a test user.

Sign in to Google Ads with a manager (MCC) account. Go to Tools & Settings → Setup → API Center. Copy your Developer Token. If the access level shows Test Account, click Apply for Basic Access and follow the application process — Google typically reviews within 5-14 business days.

Your Customer ID is the 10-digit number displayed at the top of the Google Ads UI (e.g. 123-456-7890). This identifies the specific ad account ShopMCP will query.

If you're accessing ad accounts through an MCC (Manager account), also note the MCC's own Customer ID — you'll need it as the Login Customer ID in the next step.

Open Settings → Integrations → Google Ads and click Connect with Google. Complete the OAuth consent flow — make sure you sign in with the Google account that has access to the target ad account.

After consent, fill in:

• Developer Token — the token from step 3
• Customer ID — the 10-digit ad account ID from step 4 (enter without dashes, e.g. 1234567890)
• Login Customer ID(optional) — the MCC's Customer ID, required only if you're accessing the ad account through a manager account

On submit, ShopMCP calls the Google Ads API to list accessible customers and confirms the developer token and Customer ID are valid. A successful verification persists the credentials encrypted-at-rest (KMS envelope) and flips the Google Ads module to Connected for every API key in the workspace.

ShopMCP's Google Ads package includes four write tools — google_ads_pause_campaign, google_ads_resume_campaign, google_ads_update_budget, and google_ads_add_negative_keyword. These are compiled in but never registered in v1. The runtime calls registerGoogleAdsTools({ allowWrites: false }) regardless of plan tier.

Each write tool is locked to a hand-written, field-level input allowlist. For example, google_ads_update_budget accepts amount_micros and delivery_method — and nothing else. Campaign strategy changes, bid adjustments, and audience modifications are all rejected at the input schema layer before any HTTP request is built. This is deliberate: if a prompt injection convinces the LLM to call the tool with disallowed fields, the Zod validator drops the request on the floor.

Google OAuth access tokens expire after approximately one hour. ShopMCP automatically refreshes them using the stored refresh token — the same mechanism used by the GA4 and Google Search Console modules. No manual intervention is needed unless the refresh token itself is revoked (e.g. the user removes ShopMCP from their Google account permissions).

If the refresh token is revoked, ShopMCP will surface a "Google OAuth token expired" error. Reconnect by clicking Connect with Google again to re-authorize.

• PERMISSION_DENIED — the authenticated Google account does not have access to the specified Customer ID. Verify that the account you signed in with has at least read-only access to the ad account in Google Ads.
• DEVELOPER_TOKEN_NOT_APPROVED — the developer token is still at Test Account level. Apply for Basic Access in the API Center (step 3) and wait for approval before connecting production ad accounts.
• CUSTOMER_NOT_FOUND— the Customer ID is incorrect or the account has been cancelled. Double-check the 10-digit ID in the Google Ads UI. If you're using an MCC, make sure the Login Customer ID is also set correctly.
• Rate limit exceeded (RESOURCE_EXHAUSTED) — Google Ads enforces per-developer-token rate limits. ShopMCP does not retry automatically on rate limit errors by design. Wait a few minutes and try again. If this is persistent, check your Google Ads API dashboard for quota usage.
• "Google OAuth token expired" — the refresh token was revoked. Re-authorize by clicking Connect with Google on the integration page.