Google Ads

vTilt can manage your Google Ads account through the same MCP endpoint your AI client already uses for analytics. There is no second server to run: the google_ads_* tools live in the google-ads toolset (plus an optional typed-shortcuts toolset). Calls succeed only after you connect an account in project settings (otherwise the server returns feature_disabled).

#Connect Google Ads (required first)

The Google Ads tools stay hidden until a project has a connected account; once connected, the 13-tool core is auto-listed for that project.

1. Open Project → Settings → Google Ads.
2. Click Connect Google Ads and complete the Google consent screen. vTilt requests the https://www.googleapis.com/auth/adwords scope.
3. After the redirect, vTilt discovers the accounts you can access and lists them. Pick the default account the tools should use when a call doesn't name one.
4. If you manage accounts through an MCC (manager account), set the manager (login) customer id.

vTilt stores the OAuth refresh token encrypted at rest and holds the platform developer token server-side. Your AI client never sees or sends credentials — tool inputs accept neither a refresh token nor a user id.

To stop access, click Disconnect on the same page — vTilt deletes the stored token and linked accounts. Enabled tools stay in tools/list; calls return feature_disabled until you connect again.

After switch_project, check features.google_ads in the tool response (or call get_context). Enable the google-ads toolset, then call google_ads_* tools as soon as that flag is true — re-run tools/list only if your MCP client caches the catalog.

#Permissions

Google Ads access is gated by a dedicated google_ads permission resource:

Write tools additionally require a write-scoped credential (an mcp:write OAuth scope or a personal API key with write access), and every write is recorded in the project audit log.

#Reading account data

Always learn the valid fields before querying — the tools steer you to do this so you never guess field names.

1. google_ads_get_resource_metadata — pass a resource (e.g. campaign, ad_group_ad, keyword_view) to get the selectable fields.
2. google_ads_search — assemble a read-only query from resource, fields, and optional conditions, order_by, limit. vTilt builds and validates the GAQL server-side.
3. google_ads_list_customers — see which accounts are linked to the project.

Every tool takes an optional customer_id (dashed 123-456-7890 or digits 1234567890 — both work). Omit it to use the project's default account.

A search for the last 30 days of campaign spend looks like:

{
  "resource": "campaign",
  "fields": [
    "campaign.id",
    "campaign.name",
    "metrics.cost_micros",
    "metrics.clicks"
  ],
  "conditions": [
    "campaign.status = 'ENABLED'",
    "segments.date DURING LAST_30_DAYS"
  ],
  "order_by": "metrics.cost_micros DESC",
  "limit": 25
}

#More read tools

#Managing the account (writes)

#One tool for any change: google_ads_mutate

For any create, update, or remove on any entity, use google_ads_mutate (in the core google-ads toolset). You pass raw operations and vTilt forwards them to Google:

{
  "operations": [
    {
      "campaign_criterion_operation": {
        "create": {
          "campaign": "customers/1234567890/campaigns/111",
          "negative": true,
          "keyword": { "text": "free", "match_type": "BROAD" }
        }
      }
    }
  ],
  "validate_only": true
}

#Typed shortcuts for common workflows

These live in the separate google-ads-shortcuts toolset, which is opt-in: add ?toolsets=google-ads-shortcuts (or ?toolsets=all) to your MCP URL to include them. They wrap google_ads_mutate with a friendlier schema for the most common changes — everything they do is also expressible through google_ads_mutate, so the focused 13-tool core (auto-listed when an account is connected) is enough for most workflows:

#Service tools (beyond mutations)

Some Google Ads capabilities aren't plain mutations — they have dedicated tools:

#Troubleshooting