AdWhiz

Manage Google Ads & Meta (Facebook) Ads from your AI coding tool. 113 MCP tools for auditing, creating, and optimizing ad accounts using natural language.

AdWhiz — Google Ads & Meta Ads MCP Server

AdWhiz is a hosted MCP server that connects your AI coding tool to the Google Ads API and Meta (Facebook) Graph API through a secure, authenticated proxy. It exposes 113 tools across 7 categories so you can audit, create, and manage ad campaigns across both platforms using plain English.

All API calls are authenticated via your personal ADWHIZ_API_KEY and routed through the AdWhiz server at mcp.adwhiz.ai. No Google or Meta credentials are stored by the skill — authentication is handled entirely server-side after you link your ad accounts at https://adwhiz.ai/connect.

Security & Permissions Model

• OAuth 2.0: User authenticates with Google and/or Meta via AdWhiz's web UI. Refresh tokens (Google) and long-lived access tokens (Meta) are encrypted at rest (AES-256-GCM) and never exposed to the agent.
• API key scoping: Each ADWHIZ_API_KEY is bound to a single user's connected accounts. Cross-user access is not possible.
• Write safety: All Google Ads write tools create entities in PAUSED status by default. Meta write tools require explicit status parameters.
• Mutation logging: Every mutation is recorded in the get_operation_log tool for full auditability.
• Read-only by default: 44 of 113 tools are strictly read-only and cannot modify your accounts.
• Confirmation required: Write tools require user confirmation before executing via the agent's standard permission flow.
• No arbitrary code execution: The MCP server is a hosted HTTP service. No code is downloaded or executed on the user's machine beyond the thin MCP client wrapper.

Google Ads Tools (80)

Account (2 tools) — Read-only

Tool	Description
list_accounts	List all accessible Google Ads accounts (auto-expands MCC child accounts)
get_account_info	Get account details (currency, timezone, optimization score)

Read (22 tools) — Read-only

Tool	Description
list_campaigns	List campaigns with status, type, budget, bidding strategy
get_campaign_performance	Campaign metrics: cost, clicks, conversions, CTR, CPA, ROAS
list_ad_groups	List ad groups with bids, filtered by campaign
list_ads	List ads with headlines, descriptions, final URLs
list_keywords	Keywords with match types, bids, quality scores
get_search_terms	Search terms report (actual queries triggering ads)
list_negative_keywords	Negative keywords at campaign, ad group, or account level
list_assets	Sitelinks, callouts, structured snippets
list_conversion_actions	Conversion actions with status, type, category
list_campaign_conversion_goals	Which conversion categories each campaign actually bids toward — not the same as what it reports
get_campaign_selective_optimization	The specific conversion actions a campaign optimizes toward (empty = follows category goals)
list_budgets	Campaign budgets with associated campaigns
list_bidding_strategies	Portfolio bidding strategies
list_audience_segments	Audience targeting criteria
list_user_lists	Remarketing/audience lists for targeting
get_operation_log	Recent mutations performed via AdWhiz
list_recommendations	Google Ads recommendations (add keywords, raise bids, fix ad strength)
get_change_history	Change audit log: who changed what and when
list_geo_targets	Geographic location targeting on campaigns
list_ad_schedules	Ad schedule (dayparting) criteria on campaigns
list_labels	Labels for organizing campaigns, ad groups, ads, keywords
generate_keyword_ideas	Keyword ideas with search volume, competition, bid ranges

Write (47 tools) — Requires user confirmation

Tool	Description
create_campaign	Create Search, Display, PMax, or Video campaign (starts PAUSED)
update_campaign	Update campaign name
set_campaign_status	Pause, enable, or remove a campaign
create_ad_group	Create an ad group in a campaign
update_ad_group	Update ad group name or CPC bid
set_ad_group_status	Pause, enable, or remove an ad group
create_responsive_search_ad	Create RSA with headlines + descriptions (starts PAUSED)
set_ad_status	Pause, enable, or remove an ad
add_keywords	Add keywords with match types and bids
update_keyword_bid	Change a keyword's CPC bid
set_keyword_status	Pause, enable, or remove a keyword
add_negative_keyword	Add negative keyword at campaign or ad group level
remove_negative_keyword	Remove a negative keyword
create_shared_negative_list	Create a shared negative keyword list
add_to_shared_list	Add keywords to a shared negative list
attach_shared_list	Attach shared list to a campaign
create_sitelink	Create a sitelink asset
create_callout	Create a callout asset
create_structured_snippet	Create a structured snippet asset
create_price_extension	Create a price extension asset
link_asset_to_campaign	Link asset to a campaign
unlink_asset_from_campaign	Unlink asset from a campaign
create_conversion_action	Create a conversion tracking action
update_conversion_action	Update conversion action name or status
update_campaign_conversion_goal	Set whether a campaign bids toward a conversion category (supports validate_only; refuses to leave a campaign with no biddable goal)
set_campaign_selective_optimization	Narrow a campaign to specific conversion actions, or clear it (supports validate_only; rejects REMOVED/HIDDEN actions)
create_budget	Create a campaign budget
update_budget	Update budget amount or name
create_bidding_strategy	Create a portfolio bidding strategy
add_audience_to_campaign	Add audience targeting to a campaign
update_responsive_search_ad	Update RSA headlines, descriptions, or URLs
link_asset_to_ad_group	Link asset to an ad group
unlink_asset_from_ad_group	Remove asset-to-ad-group linkage
upload_click_conversions	Upload offline click conversions (gclid-based)
upload_customer_list	Upload hashed PII to Customer Match user list
apply_recommendation	Apply a Google Ads recommendation
dismiss_recommendation	Dismiss a Google Ads recommendation
add_geo_targeting	Add geographic location targeting to a campaign
remove_geo_targeting	Remove geographic location target from a campaign
add_ad_schedule	Add ad schedule (dayparting) to a campaign
remove_ad_schedule	Remove ad schedule criterion from a campaign
set_device_bid_adjustment	Set device bid adjustment (mobile, desktop, tablet)
set_demographic_targeting	Set demographic targeting (age, gender, income)
create_label	Create a label for organizing entities
apply_label	Apply a label to a campaign, ad group, or ad
remove_label	Remove a label from a campaign, ad group, or ad
create_asset_group	Create an asset group for Performance Max campaigns

Video Ads (6 tools) — YouTube In-stream, In-feed, Shorts

Dedicated Video campaign + ad group + asset + ad creation, covering the placements Slim (MiniMax) requested daily: In-stream (YouTube videos), In-feed (discovery), and Shorts. All campaigns/ads start PAUSED.

Tool	Description
create_video_campaign	Create a Video campaign (channel_type=VIDEO). Configurable placements (YOUTUBE_VIDEOS / YOUTUBE_SHORTS / GOOGLE_VIDEO_PARTNERS) and bidding (TARGET_CPV, TARGET_CPM, MAXIMIZE_CONVERSIONS, etc.)
create_video_ad_group	Create an ad group for In-stream or Shorts ads (VIDEO_RESPONSIVE)
create_in_feed_video_ad_group	Create an ad group for In-feed (discovery) ads — YouTube home feed, search, sidebar
create_youtube_video_asset	Register a YouTube video (URL or ID) as an Asset so ads can reference it. Accepts watch, shorts, embed, youtu.be, and bare-ID formats
create_video_responsive_ad	Create a Video Responsive Ad with headline (≤15), long headline (≤90), descriptions (≤90), business name (≤25), CTA (≤10), video asset, and final URLs
create_in_feed_video_ad	Create an In-feed (discovery) Video Ad with headline (≤100), descriptions (≤35), and thumbnail variant

Audit (2 tools) — Read-only analysis

Tool	Description
run_mini_audit	Quick 3-metric audit: wasted spend, best/worst CPA, projected savings
run_full_audit	Comprehensive audit: campaigns, keywords, search terms, issues, recommendations

Query (1 tool) — Read-only, bounded

Tool	Description
run_gaql_query	Execute a read-only GAQL query against your account (max 1,000 rows, SELECT only)

Meta (Facebook) Ads Tools (33)

Meta Read (16 tools) — Read-only

Tool	Description
meta_list_ad_accounts	List all connected Meta ad accounts
meta_list_campaigns	List campaigns with status, objective, budget
meta_get_campaign_insights	Per-campaign metrics: spend, clicks, CTR, CPA, frequency (with optional breakdowns)
meta_list_ad_sets	List ad sets with targeting, status, budget, and promoted_object
meta_list_ads	List ads with creative details (title, body, image URL)
meta_get_account_insights	Account-level aggregated metrics with daily breakdown
meta_get_ad_set_insights	Per-ad-set performance metrics: spend, clicks, CPA, frequency
meta_get_ad_insights	Per-ad performance metrics: spend, clicks, conversions, CPA
meta_get_ad_creatives	List ad creatives or get creative for a specific ad
meta_search_interests	Search targetable interest audiences by keyword
meta_search_geo_locations	Search geographic locations for targeting
meta_estimate_audience_size	Estimate reach of a targeting spec
meta_get_account_pages	List Facebook pages available for running ads
meta_get_change_history	View recent changes (audit log) — who changed what and when
meta_get_instagram_media	List Instagram media with Media V2 IDs for partnership/branded content ads
meta_get_post_comments	Read comments on a Facebook/Instagram post or ad post (author, text, like count, reply count; supports pagination and top-level/all filter)

Meta Write (16 tools) — Requires user confirmation

Tool	Description
meta_set_campaign_status	Pause or activate a Meta campaign
meta_update_campaign_budget	Update a Meta campaign's daily or lifetime budget
meta_set_ad_set_status	Pause or activate a Meta ad set
meta_set_ad_status	Pause or activate a Meta ad
meta_create_campaign	Create a new Meta campaign with objective and budget
meta_create_ad_set	Create an ad set with targeting (required), optimization goal (required), budget
meta_create_ad_creative	Create ad creative with image/video, link, CTA. Supports partnership ads via source_instagram_media_id or object_story_id
meta_create_ad	Create an ad linking an ad set to a creative
meta_update_campaign	Update campaign name, budget, end time, spend cap
meta_update_ad_set	Update ad set name, budget, targeting, schedule
meta_update_ad	Update ad name, creative, or status
meta_create_custom_audience	Create custom audience from customer lists or website visitors
meta_create_lookalike_audience	Create lookalike audience from source audience
meta_upload_ad_image	Upload image from URL for ad creatives
meta_upload_partnership_video	Upload Instagram creator video via partnership ad code for branded content ads
meta_duplicate_campaign	Duplicate campaign with all ad sets and ads

Meta Audit (1 tool) — Read-only analysis

Tool	Description
meta_run_mini_audit	Quick health audit: score (0-100) across wasted spend, CPA efficiency, budget utilization, creative fatigue

MCP Server Configuration

AdWhiz uses HTTP transport to connect to the hosted MCP server. No npm packages are downloaded or executed at runtime.

json

{
  "mcpServers": {
    "adwhiz": {
      "type": "http",
      "url": "https://mcp.adwhiz.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ADWHIZ_API_KEY}"
      }
    }
  }
}

The field is "type", not "transport" — verified 2026-08-13 by running claude mcp add --transport http … and reading back what it writes to ~/.claude.json. The CLI flag is spelled --transport; the JSON key it produces is "type". Configs using "transport" are silently not recognised.

For Claude Code the one-liner is equivalent and less error-prone:

bash

claude mcp add --transport http adwhiz https://mcp.adwhiz.ai/mcp \
  --header "Authorization: Bearer $ADWHIZ_API_KEY"

Omit --header to use browser OAuth instead of an API key.

REST API (Alternative to MCP)

For platforms that cannot use the MCP protocol (GPT Actions, Dify, Coze, or any HTTP-based workflow), AdWhiz also exposes all 113 tools as a standard REST API with an OpenAPI 3.1.0 spec:

• OpenAPI spec: https://mcp.adwhiz.ai/api/v1/openapi.json
• Tool listing: https://mcp.adwhiz.ai/api/v1/tools
• Tool execution: POST https://mcp.adwhiz.ai/api/v1/tools/{tool_name}

bash

# Example: list campaigns via REST API
curl -X POST https://mcp.adwhiz.ai/api/v1/tools/list_campaigns \
  -H "Authorization: Bearer $ADWHIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "1234567890"}'

Import the OpenAPI spec URL into any platform that supports OpenAPI actions to auto-discover all 113 tools.

Quick Install

bash

clawhub install adwhiz

This adds the MCP server configuration above to your settings. You will be prompted to provide your ADWHIZ_API_KEY.

Getting Your API Key

1. Sign up at https://adwhiz.ai
2. Connect your Google Ads and/or Meta Ads account via OAuth
3. Copy your API key from the dashboard settings page

Example Prompts

Google Ads

• "Audit my Google Ads account and show the top 5 waste areas"
• "Pause all campaigns with CPA above $150"
• "Add these negative keywords to my Search campaigns: [list]"
• "Create a new Search campaign targeting lawyers in New York with $100/day budget"
• "Show me search terms wasting money and suggest negatives"
• "What is my account's average Quality Score this month?"

Meta Ads

• "Audit my Meta Ads account and show the health score"
• "List all active Meta campaigns with their spend and CTR"
• "Pause the Meta campaign with the highest frequency"
• "Show me daily spend trends for my Meta account over the last 30 days"
• "Which Meta ad sets have the worst CPA?"

Data Handling

• AdWhiz only accesses the ad accounts you explicitly linked
• No campaign data is stored beyond the duration of each API request
• Mutation logs are retained for 30 days for auditability
• You can revoke access at any time from https://adwhiz.ai/connect

Documentation

Full documentation: https://adwhiz.ai/docs