Aidvertaiser
AI-powered advertising management via MCP. 232 tools across 8 platforms — Google Ads, Meta Ads, GA4, Search Console, Tag Manager, Matomo, Bing Webmaster, and PageSpeed Insights.
Open source. One server. Works with Claude, Cursor, Windsurf, and any MCP client.
Platforms
| Platform | Prefix | Tools | Auth |
|---|
| Google Ads | google_ | 81 | OAuth (browser) |
| Meta Ads | meta_ | 40 | OAuth (browser) |
| Google Analytics (GA4) | ga4_ | 31 | OAuth (browser) |
| Google Search Console | gsc_ | 18 | OAuth (browser) |
| Google Tag Manager | gtm_ | 14 | OAuth (browser) |
| Matomo Analytics | matomo_ | 24 | API token |
| Bing Webmaster Tools | bing_ | 21 | API key |
| PageSpeed Insights | pagespeed_ | 3 | API key (optional) |
Installation
# From source
git clone https://github.com/Draivix/aidvertaiser.git
cd aidvertaiser
uv sync
Quick Start
Add to your MCP client config (e.g. ~/.claude/mcp_servers.json):
{
"aidvertaiser": {
"command": "uv",
"args": ["run", "--directory", "/path/to/aidvertaiser", "unified-ads-mcp"]
}
}
Or run directly:
uv run unified-ads-mcp
Configuration
All config files live in ~/.unified-ads-mcp/. Create this directory first:
mkdir -p ~/.unified-ads-mcp
OAuth tokens are cached here automatically after first browser-based authentication.
Google Ads
Create ~/.unified-ads-mcp/google-ads.yaml:
developer_token: YOUR_DEVELOPER_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
login_customer_id: YOUR_MCC_ID # Optional, for MCC access
default_customer_id: YOUR_CUSTOMER_ID # Optional, skip account listing
Env var override: GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
Tip: Set ONLY_DEFAULT_ACCOUNT=1 to disable google_list_accounts and force using the default customer ID everywhere. Useful when you only manage one account.
Meta Ads
Create ~/.unified-ads-mcp/meta-ads.yaml:
app_id: YOUR_APP_ID
app_secret: YOUR_APP_SECRET
access_token: YOUR_TOKEN # Optional, bypasses browser OAuth
default_account_id: act_XXXXXXXXXX # Optional
Or set environment variables: META_APP_ID, META_APP_SECRET, META_ACCESS_TOKEN.
Env var override: META_ADS_CREDENTIALS=/path/to/meta-ads.yaml
Google Analytics (GA4)
Create ~/.unified-ads-mcp/google-analytics.yaml:
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
default_property_id: YOUR_PROPERTY_ID # Optional
Falls back to google-ads.yaml for client_id/client_secret (same Google Cloud project).
Env var override: GOOGLE_ANALYTICS_CREDENTIALS=/path/to/google-analytics.yaml
Google Search Console
Uses google-ads.yaml for client credentials (same Google Cloud project). No separate config needed.
Also provides the Indexing API for submitting URLs. Requires the Web Search Indexing API enabled in Google Cloud Console.
Google Tag Manager
Create ~/.unified-ads-mcp/google-tagmanager.yaml:
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
default_account_id: YOUR_GTM_ACCOUNT_ID # Optional
default_container_id: YOUR_GTM_CONTAINER_ID # Optional
Falls back to google-ads.yaml for client_id/client_secret.
Env var override: GOOGLE_TAGMANAGER_CREDENTIALS=/path/to/google-tagmanager.yaml
Matomo Analytics
Create ~/.unified-ads-mcp/matomo.yaml:
url: https://your-matomo-instance.com
token_auth: YOUR_API_TOKEN
default_site_id: 1 # Optional
Env var override: MATOMO_CREDENTIALS=/path/to/matomo.yaml
Bing Webmaster Tools
Create ~/.unified-ads-mcp/bing-webmaster.yaml:
api_key: YOUR_API_KEY
default_site_url: https://yoursite.com # Optional
Get the API key from: Bing Webmaster Tools > Settings > API Access > Generate API Key.
Env var override: BING_WEBMASTER_CREDENTIALS=/path/to/bing-webmaster.yaml
PageSpeed Insights
No config needed for basic usage (rate-limited to ~5 requests/min without an API key).
For higher limits, create ~/.unified-ads-mcp/pagespeed.yaml:
api_key: YOUR_GOOGLE_API_KEY # 25,000 requests/day
Or set PAGESPEED_API_KEY env var.
Available Tools
Google Ads — 81 tools
Accounts & Reporting:
google_list_accounts — List accessible Google Ads accountsgoogle_get_account_summary — Account overview with metricsgoogle_run_query — Execute raw GAQL queries
Campaigns:
google_list_campaigns — List campaigns with optional status filtergoogle_get_campaign — Single campaign detailsgoogle_create_campaign — Create a Search campaigngoogle_create_pmax_campaign — Create a Performance Max campaigngoogle_update_campaign — Update campaign settingsgoogle_delete_campaign — Remove a campaigngoogle_get_campaign_performance — Campaign performance metricsgoogle_set_campaign_conversion_goal — Set conversion goalsgoogle_set_campaign_locations — Set geographic targetinggoogle_set_campaign_languages — Set language targetinggoogle_set_ad_schedule — Set day/time ad schedulinggoogle_set_device_bid_adjustment — Adjust bids by device typegoogle_set_demographic_exclusions — Exclude age/gender demographicsgoogle_set_tracking_template — Set tracking URL template at account or campaign level
Bulk Operations & Automation:
google_bulk_set_campaign_status — Pause/enable multiple campaigns at oncegoogle_bulk_update_keywords — Batch update keyword status/bidsgoogle_list_holidays — List state holidays for a countrygoogle_run_holiday_check — Check if today is a holidaygoogle_set_holiday_schedule — Auto-pause campaigns on holidays
Labels:
google_list_labels — List all labelsgoogle_create_label — Create a labelgoogle_delete_label — Remove a labelgoogle_assign_label_to_campaigns — Assign label to campaignsgoogle_remove_label_from_campaigns — Remove label from campaignsgoogle_get_campaigns_by_label — Get campaigns by label
Ad Groups:
google_list_ad_groups — List ad groups in a campaigngoogle_get_ad_group — Single ad group detailsgoogle_create_ad_group — Create an ad groupgoogle_update_ad_group — Update ad group settingsgoogle_delete_ad_group — Remove an ad group
Ads:
google_list_ads — List ads in an ad groupgoogle_get_ad — Single ad detailsgoogle_create_responsive_search_ad — Create a responsive search adgoogle_update_ad — Update ad contentgoogle_delete_ad — Remove an adgoogle_get_ad_performance — Ad performance metrics
Keywords:
google_list_keywords — List keywords in an ad groupgoogle_get_keyword — Single keyword details with Quality Scoregoogle_add_keywords — Add keywords to an ad groupgoogle_update_keyword — Update keyword bid/statusgoogle_remove_keyword — Remove a keywordgoogle_get_keyword_performance — Keyword performance metricsgoogle_get_search_terms_report — Search terms triggering adsgoogle_add_negative_keywords — Add negative keywords (ad group level)google_list_negative_keywords — List negative keywords (ad group level)google_remove_negative_keyword — Remove a negative keyword (ad group level)google_add_campaign_negative_keywords — Add negative keywords (campaign level)google_list_campaign_negative_keywords — List negative keywords (campaign level)google_remove_campaign_negative_keyword — Remove a negative keyword (campaign level)
Conversions:
google_list_conversion_actions — List conversion actionsgoogle_get_conversion_action — Conversion action detailsgoogle_create_conversion_action — Create a conversion actiongoogle_update_conversion_action — Update conversion actiongoogle_delete_conversion_action — Remove a conversion actiongoogle_get_conversion_action_performance — Conversion performancegoogle_upload_offline_conversions — Upload offline conversion datagoogle_upload_enhanced_conversions — Upload enhanced conversionsgoogle_list_customer_conversion_goals — List account-level conversion goalsgoogle_update_customer_conversion_goal — Update conversion goal settings
Assets:
google_list_assets — List account assetsgoogle_create_text_asset — Create a text assetgoogle_create_text_assets_batch — Create multiple text assetsgoogle_create_image_asset — Create an image assetgoogle_link_asset_to_campaign — Link asset to a campaigngoogle_create_sitelink_asset — Create a sitelink extensiongoogle_create_callout_asset — Create a callout extensiongoogle_create_structured_snippet_asset — Create a structured snippet extension
Performance Max Asset Groups:
google_list_asset_groups — List PMax asset groupsgoogle_get_asset_group — Asset group detailsgoogle_create_asset_group — Create a PMax asset groupgoogle_update_asset_group — Update asset groupgoogle_delete_asset_group — Remove an asset groupgoogle_add_asset_group_asset — Add asset to groupgoogle_remove_asset_group_asset — Remove asset from groupgoogle_get_asset_automation_settings — Get auto-asset settingsgoogle_update_asset_automation_settings — Update auto-asset settingsgoogle_list_auto_created_assets — List auto-created assetsgoogle_remove_auto_created_asset — Remove an auto-created asset
Meta Ads — 40 tools
Accounts:
meta_list_accounts — List accessible ad accountsmeta_get_account_info — Account detailsmeta_get_login_link — Get OAuth login URL
Campaigns:
meta_list_campaigns — List campaignsmeta_get_campaign_details — Campaign detailsmeta_create_campaign — Create a campaignmeta_update_campaign — Update campaign settings
Ad Sets:
meta_list_adsets — List ad setsmeta_get_adset_details — Ad set detailsmeta_create_adset — Create an ad setmeta_update_adset — Update ad set settings
Ads & Creatives:
meta_list_ads — List adsmeta_get_ad_details — Ad detailsmeta_create_ad — Create an admeta_update_ad — Update ad settingsmeta_get_ad_creatives — Creative detailsmeta_create_creative — Create a creativemeta_update_creative — Update a creativemeta_upload_image — Upload image for ads
Insights:
meta_get_insights — Performance reports
Targeting:
meta_search_interests — Search interest targetingmeta_get_interest_suggestions — Interest suggestionsmeta_search_behaviors — Search behavior targetingmeta_search_geo_locations — Search geographic locationsmeta_estimate_audience_size — Estimate audience size
Tracking Pixels:
meta_list_pixels — List tracking pixelsmeta_get_pixel — Pixel detailsmeta_create_pixel — Create a pixelmeta_update_pixel — Update pixel settingsmeta_get_pixel_stats — Pixel event statistics
Conversions:
meta_send_conversion_event — Send a Conversions API eventmeta_send_conversion_events_batch — Send batch eventsmeta_list_custom_conversions — List custom conversionsmeta_get_custom_conversion — Custom conversion detailsmeta_create_custom_conversion — Create custom conversionmeta_update_custom_conversion — Update custom conversionmeta_delete_custom_conversion — Delete custom conversionmeta_list_offline_conversion_sets — List offline conversion setsmeta_create_offline_conversion_set — Create offline conversion setmeta_upload_offline_conversions — Upload offline conversions
Google Analytics (GA4) — 31 tools
Accounts & Properties:
ga4_list_accounts — List GA4 accountsga4_list_account_summaries — Account summariesga4_list_properties — List properties in an accountga4_get_property — Property detailsga4_create_property — Create a propertyga4_update_property — Update property settingsga4_delete_property — Remove a property
Data Streams:
ga4_list_data_streams — List data streamsga4_get_data_stream — Data stream detailsga4_create_web_data_stream — Create web data streamga4_create_android_data_stream — Create Android data streamga4_create_ios_data_stream — Create iOS data streamga4_update_data_stream — Update data streamga4_delete_data_stream — Remove a data streamga4_get_tracking_code — Get tracking code snippet
Reporting:
ga4_run_report — Standard analytics reportga4_run_realtime_report — Real-time dataga4_get_metadata — Available dimensions and metrics
Key Events:
ga4_list_key_events — List key events (conversions)ga4_create_key_event — Create a key eventga4_update_key_event — Update key eventga4_delete_key_event — Remove a key event
Custom Dimensions:
ga4_list_custom_dimensions — List custom dimensionsga4_create_custom_dimension — Create a custom dimensionga4_update_custom_dimension — Update display name or descriptionga4_archive_custom_dimension — Archive (soft-delete) a custom dimension
Measurement Protocol:
ga4_send_measurement_protocol_event — Send server-side eventga4_send_measurement_protocol_batch — Send batch server-side eventsga4_list_measurement_protocol_secrets — List API secrets for a data streamga4_create_measurement_protocol_secret — Create an API secretga4_delete_measurement_protocol_secret — Delete an API secret
Google Search Console — 18 tools
Sites:
gsc_list_sites — List registered sitesgsc_get_site — Site detailsgsc_add_site — Register a sitegsc_delete_site — Remove a site
Search Analytics:
gsc_search_analytics — Full search traffic data (clicks, impressions, CTR, position)gsc_search_analytics_by_query — Top search queriesgsc_search_analytics_by_page — Top pages by performance
URL Inspection:
gsc_inspect_url — Check indexing status
Indexing API:
gsc_submit_url_for_indexing — Submit a URL for indexinggsc_submit_urls_for_indexing — Batch submit URLs (~200/day limit)gsc_get_indexing_notification_status — Check indexing notification status
Sitemaps:
gsc_list_sitemaps — List submitted sitemapsgsc_get_sitemap — Sitemap detailsgsc_submit_sitemap — Submit a sitemapgsc_delete_sitemap — Remove a sitemap
Verification:
gsc_get_verification_token — Get verification tokengsc_verify_site — Verify site ownershipgsc_list_verified_sites — List all verified sites
Google Tag Manager — 14 tools
Accounts & Containers:
gtm_list_accounts — List GTM accountsgtm_list_containers — List containersgtm_list_workspaces — List workspaces
Tags:
gtm_list_tags — List tags in a workspacegtm_create_tag — Create a tag (GA4, Google Ads, custom HTML, etc.)gtm_update_tag — Update tag settingsgtm_delete_tag — Remove a tag
Triggers:
gtm_list_triggers — List triggersgtm_create_trigger — Create a trigger (page view, click, custom event, etc.)gtm_update_trigger — Update trigger settingsgtm_delete_trigger — Remove a trigger
Versions & Publishing:
gtm_list_versions — Version historygtm_create_version — Create a version from workspacegtm_publish_version — Publish a version (makes changes live)
Matomo Analytics — 24 tools
Sites:
matomo_list_sites — List tracked websitesmatomo_get_site — Site detailsmatomo_add_site — Add a websitematomo_update_site — Update site settingsmatomo_delete_site — Remove a sitematomo_get_site_urls — Get URLs for a sitematomo_get_tracking_code — Get tracking code snippet
Reporting:
matomo_get_visits_summary — Basic visit metricsmatomo_get_page_urls — Page URL performancematomo_get_entry_pages — Top entry pagesmatomo_get_exit_pages — Top exit pagesmatomo_get_referrers — Referrer sourcesmatomo_get_referrer_types — Referrer type breakdownmatomo_get_search_keywords — Internal search keywordsmatomo_get_countries — Visitor countriesmatomo_get_devices — Visitor devices
Live:
matomo_get_live_counters — Real-time active visitorsmatomo_get_last_visits — Recent visit detailsmatomo_get_visitor_profile — Individual visitor profile
Goals:
matomo_list_goals — List goalsmatomo_add_goal — Create a goalmatomo_update_goal — Update a goalmatomo_delete_goal — Remove a goalmatomo_get_goal_report — Goal conversion report
Bing Webmaster Tools — 21 tools
Sites:
bing_list_sites — List registered sitesbing_add_site — Register a sitebing_verify_site — Verify site ownershipbing_remove_site — Remove a site
URL Submission:
bing_submit_url — Submit a URL for crawlingbing_submit_url_batch — Batch submit up to 500 URLsbing_get_url_submission_quota — Check daily submission quota
Sitemaps:
bing_list_sitemaps — List submitted sitemapsbing_submit_sitemap — Submit a sitemapbing_remove_sitemap — Remove a sitemap
Search Analytics:
bing_get_rank_and_traffic_stats — Overall search performancebing_get_query_stats — Per-query metricsbing_get_page_stats — Per-page metrics
Crawl Management:
bing_get_crawl_stats — Crawl activity statisticsbing_get_crawl_issues — Crawl errorsbing_get_crawl_settings — Current crawl rate settingsbing_save_crawl_settings — Update crawl rate (1–10)
Keyword Research:
bing_get_keyword — Search volume for a keywordbing_get_related_keywords — Related keyword suggestions
Link Analysis:
bing_get_link_counts — Total inbound link countsbing_get_url_links — Detailed inbound link list
PageSpeed Insights — 3 tools
pagespeed_analyze — Full Lighthouse audit (scores, Core Web Vitals, opportunities)pagespeed_compare — Mobile vs desktop side-by-side comparisonpagespeed_core_web_vitals — Chrome UX Report field data (LCP, INP, CLS, FCP, TTFB)
Required Google Cloud APIs
Enable these in your Google Cloud Console:
| API | Required for | Enable command |
|---|
| Google Ads API | google_* | gcloud services enable googleads.googleapis.com |
| Google Analytics Admin API | ga4_* | gcloud services enable analyticsadmin.googleapis.com |
| Google Analytics Data API | ga4_run_report, ga4_run_realtime_report | gcloud services enable analyticsdata.googleapis.com |
| Google Search Console API | gsc_* | gcloud services enable searchconsole.googleapis.com |
| Web Search Indexing API | gsc_submit_url_for_indexing | gcloud services enable indexing.googleapis.com |
| Tag Manager API | gtm_* | gcloud services enable tagmanager.googleapis.com |
| Site Verification API | gsc_verify_site | gcloud services enable siteverification.googleapis.com |
| PageSpeed Insights API | pagespeed_* (optional) | gcloud services enable pagespeedonline.googleapis.com |
Authentication
OAuth platforms (Google Ads, Meta, GA4, Search Console, Tag Manager):
- On first use, a local OAuth server starts on
localhost:8888+
- Browser opens automatically with the consent page
- User completes authentication
- Token is cached to
~/.unified-ads-mcp/
- Tokens auto-refresh on subsequent runs
Cached token files:
~/.unified-ads-mcp/google_ads_token.json~/.unified-ads-mcp/google_analytics_token.json~/.unified-ads-mcp/google_searchconsole_token.json~/.unified-ads-mcp/google_tagmanager_token.json~/.unified-ads-mcp/meta_token.json
To force re-authentication (e.g. after adding OAuth scopes), delete the relevant token file.
API key/token platforms (Matomo, Bing, PageSpeed): No browser flow — credentials are read directly from YAML config.
Environment Variables
| Variable | Purpose |
|---|
GOOGLE_ADS_CREDENTIALS | Path to Google Ads YAML config |
GOOGLE_ANALYTICS_CREDENTIALS | Path to GA4 YAML config |
GOOGLE_TAGMANAGER_CREDENTIALS | Path to Tag Manager YAML config |
META_ADS_CREDENTIALS | Path to Meta Ads YAML config |
META_APP_ID | Meta app ID (alternative to YAML) |
META_APP_SECRET | Meta app secret (alternative to YAML) |
META_ACCESS_TOKEN | Meta access token (bypasses OAuth) |
MATOMO_CREDENTIALS | Path to Matomo YAML config |
BING_WEBMASTER_CREDENTIALS | Path to Bing YAML config |
PAGESPEED_API_KEY | Google PageSpeed API key |
ONLY_DEFAULT_ACCOUNT | Set to 1 to force using default customer ID |
License
MIT
