Gentic Google Ads — Documentation

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Google Ads, you need an API key to authenticate your requests.

1. Go to gentic.co/google-ads and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/google-ads. For Claude Code:

claude mcp add gentic-google-ads \
  --transport http \
  https://mcp.gentic.co/google-ads \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Google Ads agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/google-ads/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/google-ads/gentic-google-ads.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

• User wants to create, manage, or optimize Google Search campaigns.
• User wants to research keywords with search volume, competition, and bid estimates.
• User wants to analyze Google Ads performance (spend, clicks, conversions, CTR, CPA, ROAS).
• User wants to create responsive search ads with headlines and descriptions.
• User wants to see which search terms are triggering their ads.
• User wants to run arbitrary GAQL queries against their Google Ads data.
• User wants to adjust campaign budgets, ad group CPC bids, or toggle campaign status (pause/enable).
• User wants to pause, enable, or remove individual ad groups or ads.
• User wants to add negative keywords to stop ads from showing on irrelevant queries.
• User wants to switch which Google Ads account (or MCC login account) the agent operates against.

5. Workflow

1. 1. Check connection with `google_ads_connection_status`

   Free call — returns whether the org has connected a Google Ads account, plus the selected customer ID. If not connected, direct the user to the Gentic dashboard Integrations section to authorize via OAuth. Use `list_accessible_customers` (also free) to see all accounts the credentials can access, keep only the ones where status is ENABLED and manager is false (manager accounts can't serve campaigns), then switch with `select_google_ads_account` — pass `loginCustomerId` to the MCC if the account is accessed via a manager. `select_google_ads_account` runs a smoke GAQL query and returns `verified: true/false` so you catch a bad combination before making real calls.

2. 2. Research keywords with `generate_keyword_ideas` (25¢/call)

   Provide seed `keywords`, a `pageUrl`, or both. Returns per-keyword average monthly searches, competition level (LOW/MEDIUM/HIGH), and top-of-page bid range in micros. Filter by `language` (default "en"), `geoTargetLocations` (default ["US"]), and `network`. Paginate with `pageSize` and `pageToken` for large result sets.

3. 3. Create the campaign structure (25¢ per mutating call)

   Build bottom-up: `create_campaign_budget` (daily amount in micros — 1 USD = 1,000,000) → `create_search_campaign` (references the budget, choose MANUAL_CPC or TARGET_CPA) → `create_ad_group` (set default CPC bid) → `add_keywords` (1-200 keywords with BROAD/PHRASE/EXACT match types) → `create_responsive_search_ad` (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). **Everything defaults to PAUSED.** To create ENABLED campaigns that spend immediately, pass `status="ENABLED"` AND `confirmEnableSpend=true`.

4. 4. Pull structured performance with `get_campaign_performance` (15¢/call)

   Returns impressions, clicks, cost, conversions, CTR, CPA, and ROAS grouped by campaign. Use `dateRange` with a preset (`LAST_7_DAYS`, `LAST_30_DAYS`, etc.) or custom `startDate`/`endDate`. Drill down with `get_ad_group_performance` and `get_keyword_performance` (both 15¢). Filter by `campaignId` or `adGroupId` to narrow results.

5. 5. Get AI-narrated analysis with `analyze_campaign` (50¢/call)

   Pulls performance for the requested period and the prior equivalent period, then returns a ranked narrative comparing the two with winners, losers, and concrete recommendations. Use this when the user wants strategic insights rather than raw numbers. Filter to specific campaigns with `campaignIds`.

6. 6. Investigate search terms with `get_search_terms_report` (15¢/call)

   Shows the actual user queries that triggered ads — critical for finding negative keyword candidates and wasted spend. Filter by `campaignId`, `adGroupId`, and `minImpressions`. Present results as a ranked table by impressions or cost, highlighting irrelevant queries the user should add as negatives.

7. 7. Exclude irrelevant queries with `add_negative_keywords` (25¢/call)

   Once you've identified wasted spend in the search terms report, use `add_negative_keywords` to stop ads from serving on those queries. Pass `level: "campaign"` with `campaignResourceName` to exclude across the whole campaign (most common), or `level: "adGroup"` with `adGroupResourceName` for narrower exclusion. 1–200 keywords per call, each with a `matchType` of BROAD, PHRASE, or EXACT.

8. 8. Run arbitrary queries with `run_gaql_query` (15¢/call)

   Execute any Google Ads Query Language query when the built-in tools don't cover a specific metric or dimension. Capped at 1,000 rows per call — paginate with `pageSize` and `pageToken`. Use this for edge cases like segmenting by device, hour of day, or custom attribute combinations.

9. 9. Adjust budgets, bids, and status after launch (25¢ per mutating call)

   Once campaigns are live, use `update_campaign_budget` to change the daily amount (in micros) on an existing budget resource, `update_ad_group_bid` to change an ad group's default CPC (also in micros — sanity-check the digit count), and `update_campaign_status` / `update_ad_group_status` / `update_ad_status` to pause, enable, or remove a campaign, ad group, or individual ad. Status accepts `ENABLED`, `PAUSED`, or `REMOVED`. Note that `update_ad_status` takes the `AdGroupAd` resource name, not a raw ad ID; transitioning anything to `ENABLED` is gated by `confirmEnableSpend: true`, and transitioning to `REMOVED` is gated by `confirmRemove: true` — see Notes for all three.

10. 10. Present results clearly

    For performance: lead with the headline metric (spend, CTR, top performer), show a ranked table, and call out outliers or period-over-period changes. For campaign creation: echo back the resource names, budget (in dollars, not micros), bidding strategy, and the fact that everything is **PAUSED — needs manual activation**. For keyword research: rank by search volume, highlight low-competition/high-volume opportunities.

6. Tool Reference

21 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

8. Notes

• **OAuth required.** Users must connect their Google Ads account via the Gentic dashboard before the agent can access any tools (except `google_ads_connection_status`, `list_accessible_customers`, and `select_google_ads_account` — all free).
• `customerId` is optional on most tools — if omitted, it uses the `selected_customer_id` stored on the connection. Change the default with `select_google_ads_account`, or pass `customerId` explicitly on a single call to operate on a different account.
• **MCC accounts:** if the target customer is accessed via a manager account, set `loginCustomerId` on `select_google_ads_account` to that manager's 10-digit ID. Pass `loginCustomerId: null` only for direct-access, non-managed accounts. `select_google_ads_account` verifies the combination with a smoke GAQL query and returns `verified: false` + `verificationError` if the credentials don't actually work — check this before making real calls.
• **Budgets and bids are in micros** — 1 USD = 1,000,000 micros. `amountMicros: "5000000"` = $5/day.
• All campaigns, ad groups, and ads are created in **PAUSED** status by default. Enabling spend — at creation OR via `update_campaign_status` / `update_ad_group_status` / `update_ad_status` — requires `status: "ENABLED"` AND `confirmEnableSpend: true`.
• Removing a campaign, ad group, or ad via `update_*_status` with `status: "REMOVED"` requires `confirmRemove: true` and is **irreversible** — Google Ads cannot restore a removed entity. Prefer `PAUSED` if you only want to stop serving.
• `update_ad_status` operates on the `AdGroupAd` resource. Use the `adGroupAdResourceName` returned by `create_responsive_search_ad` (format `customers/{cid}/adGroupAds/{adGroupId}~{adId}`), not the raw ad ID.
• `update_ad_group_bid` takes `cpcBidMicros` in micros (1 USD = 1,000,000). Double-check the digit count before submitting and confirm the dollar amount with the user when it exceeds 20,000,000 ($20/click).
• Responsive search ads require **3-15 headlines** (≤30 chars each) and **2-4 descriptions** (≤90 chars each). Use `pinnedField` to lock a headline or description to a specific position.
• `path1` / `path2` on responsive search ads are cosmetic breadcrumbs on the displayed URL — they don't need to match a real route on `finalUrls`. Omit them entirely to show only the bare domain.
• `create_search_campaign` defaults `containsEuPoliticalAdvertising` to `DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING` — required by EU TTPA on every new campaign. Pass `CONTAINS_EU_POLITICAL_ADVERTISING` only when the campaign actually runs EU political ads.
• Strongly recommended to pass `geoTargetLocations` (e.g. `["US"]`) and `language` (e.g. `"en"`) on `create_search_campaign` — if omitted, the campaign serves globally in all languages, which usually wastes budget.
• `generate_keyword_ideas` needs at least one of `keywords` or `pageUrl`. Provide both for the best results.
• `run_gaql_query` is capped at 1,000 rows per call. Use `pageSize` and `pageToken` for pagination.
• Performance tools cost 15¢/call, mutating tools cost 25¢/call, and `analyze_campaign` costs 50¢/call. Connection, account listing, and account selection are free.
• All tools are organization-scoped — users only see their own Google Ads accounts.