HTMLToolz Ads MCP

htmltoolz-ads-mcp is a safe paid-media operations connector for MCP clients. It connects an assistant to the customer's own Google Ads account for reporting, budget pacing, waste analysis, campaign reviews, and deliberately confirmed changes.

It is not a credential relay. The MCP process has one secret—an HTMLToolz API key. Google and Microsoft OAuth grants, refresh tokens, developer tokens, and client secrets remain encrypted on the HTMLToolz server.

What is live

Google Ads is the live operational surface. The connector runs against Google Ads API v24 and includes:

• Account, campaign, daily, ad-group, keyword, and search-term reporting
• Derived metrics that are useful to an operator: CPA, conversion rate, and ROAS
• This-month budget pacing and projected over/under-spend
• Campaign health checks and a zero-conversion search-term waste audit
• Keyword ideas and guarded, read-only GAQL
• Change previews before a live write
• Pausing/enabling campaigns, setting daily budgets, adding campaign negatives, and creating a basic Search campaign in PAUSED state
• A server-side activity trail for successful live changes

Microsoft Advertising OAuth can be connected and verified. Microsoft campaign management is intentionally not exposed until account mapping and Microsoft Advertising management configuration are complete; this connector does not pretend that an OAuth refresh is a working management integration.

Security model

MCP client --stdio--> htmltoolz-ads-mcp --HTTPS with htk_ key--> HTMLToolz
                                                               |
                                                        plan + entitlement check
                                                        encrypted OAuth grant
                                                        Google Ads API v24

The Ads add-on entitlement (ads_access) is required for every connector call. Live writes also require ads_write.

Every live write requires all three of the following:

1. A human reviews a report or google_ads_preview_change result.
2. The tool call contains confirm: "APPLY".
3. The tool call contains a 3–280 character change_reason, retained in the activity trail.

The HTMLToolz backend enforces those checks even if a caller bypasses the MCP package. New Search campaigns are always created PAUSED; enabling a campaign is a separate confirmed operation.

Install

npx -y htmltoolz-ads-mcp

Set HTMLTOOLZ_API_KEY to an Ads add-on key. HTMLTOOLZ_API_URL defaults to https://htmltoolz.com and can be overridden for local or self-hosted development.

{
  "mcpServers": {
    "htmltoolz-ads": {
      "command": "npx",
      "args": ["-y", "htmltoolz-ads-mcp"],
      "env": { "HTMLTOOLZ_API_KEY": "htk_live_xxx" }
    }
  }
}

Connect Google Ads first at https://htmltoolz.com/account#ads. Never put a Google or Microsoft token in the MCP configuration.

Develop from source

cd mcp-ads
npm ci
HTMLTOOLZ_API_KEY=htk_live_xxx node src/cli.js

Operator workflow

Start each session with ads_connection_status. A productive, safe loop is:

1. google_ads_account_overview and google_ads_budget_pacing
2. google_ads_campaign_health and google_ads_waste_audit
3. google_ads_preview_change for every proposed budget, status, or negative-keyword change
4. Make one corresponding confirmed write, with confirm: "APPLY" and change_reason
5. Check ads_activity_log and rerun the relevant report

This deliberately favors reviewable changes over broad autonomous edits to a live ad account.

Tool catalog

| Area | Tools | | --- | --- | | Control plane | ads_connection_status, ads_activity_log | | Inventory | google_ads_list_accounts, google_ads_list_campaigns | | Performance | google_ads_account_overview, google_ads_campaign_report, google_ads_daily_performance, google_ads_ad_group_report, google_ads_keyword_report, google_ads_search_terms_report | | Decision support | google_ads_budget_pacing, google_ads_campaign_health, google_ads_waste_audit, google_ads_keyword_ideas, google_ads_search | | Safety | google_ads_preview_change | | Confirmed writes | google_ads_create_search_campaign, google_ads_update_campaign_status, google_ads_update_campaign_budget, google_ads_add_campaign_negative_keyword | | Microsoft diagnostic | microsoft_ads_verify_auth |

google_ads_search accepts a single GAQL SELECT statement only. It rejects multi-statement and mutating keywords even though it is sent through a read endpoint.

Example prompts

Show account performance and budget pacing for this month. Flag any campaign
projected to exceed its monthly budget.

Run a 30-day waste audit. For the three expensive zero-conversion search terms,
show me a preview of adding each as an exact negative. Do not make changes yet.

I reviewed the preview. Set budget 987654 to 45.00. Use confirm APPLY and the
reason "Moved spend from the underperforming prospecting campaign".

HTMLToolz operator setup

From the HTMLToolz application root:

php scripts/sql_ads.php

This installs the encrypted connection store and the Ads activity trail. Configure the Google OAuth client ID/secret and Google Ads developer token in protected admin options:

• cfg_ads_google_client_id
• cfg_ads_google_client_secret
• cfg_ads_google_developer_token
• cfg_ads_google_login_customer_id (optional manager-account ID)

See ../INTEGRATION-ads.md for redirect URIs, Microsoft setup, and billing configuration.

Development

npm install
npm test

The smoke test starts a mock HTMLToolz backend and verifies license gating, the full MCP catalog, control-plane calls, local write confirmation, and backend write rejection propagation.

License

Commercial. Requires an active HTMLToolz Ads add-on subscription.