mcp-microsoft-ads

Draft an ad-group update. target_cpa sets an explicit MaxConversions tCPA on the ad group (MS Search campaigns on the development account run MaxConversions with no target — this INTRODUCES one). cpc_bid is allowed ONLY when the ad group's effective bid strategy is in the MANUAL_BIDDING allowlist (r…

Draft a Responsive Search Ad. 3-15 headlines, 2-4 descriptions. Ad copy claims MUST be verified against the advertiser's website before use — don't claim anything not actually present on the site (site-verified-claims policy). Blocklist (settings-configured blocked_terms) enforced on every headline/…

Draft a remarketing list targeting site visitors (needs the account's UET tag; errors if none exists — create one in the MS Ads UI first). url_contains: substring the visited page URL must contain; defaults to the configured advertiser_domain setting when omitted — error naming both if neither is se…

Draft audience targeting on a campaign. audience_type disambiguates which id namespace audience_id is in — one of: RemarketingList, Custom, InMarket, Product, SimilarRemarketingList, CombinedList, CustomerList, ImpressionBasedRemarketingList, CustomSegment (WSDL AudienceType enum). bid_adjustment_pc…

Draft a campaign update (budget / status Active|Paused / tCPA). tCPA at campaign level is only operative on PMax — for Search use update_ad_group. Returns a draft; apply with confirm_and_apply.

Draft a new campaign — ALWAYS created Paused. campaign_type: Search | PerformanceMax. time_zone/language default to EasternTimeUSCanada/English (US-centric defaults) — override for other markets.

Execute a previously drafted write. The ONLY path that mutates the account.

Draft a conversion goal. goal_type: Event | Url | Duration (only supported values on the development account). Each goal_type REQUIRES its matching match-criteria arg — without one the goal creates "successfully" but can never record a conversion: - Url: url_expression (matched with UrlOperator="Con…

Draft a campaign-goal association. MS models 'primary for this campaign' as a campaign conversion goal association (associate = campaign optimizes to it; disassociate = falls back to account-level goals).

Fetch entity state. entity: campaigns | ad_groups | keywords | ads | asset_groups | campaign_criterions. parent_id required for all but campaigns. campaign_criterions returns DayTime, Location, LocationIntent, Radius criterion types (Audience not readable via this API). NOTE: campaign BiddingScheme …

Draft sitelinks on a campaign. sitelinks: [{text, url, description1?, description2?}]. Copy claims must be site-verified (the advertiser's website).

Draft callout extensions (max 25 chars each).

Draft a structured snippet (header must be an MS-supported header, e.g. 'Services'; 3+ values required).

Draft removal: disassociate from campaign, then delete from library.

Search targetable/excludable locations by name (MS ships a file, not a query API; cached locally 30 days). Returns location ids for geo write tools.

Draft a location EXCLUSION on a campaign. location_id from search_geo_targets.

Draft removal of a campaign criterion by id, via DeleteCampaignCriterions with CriterionType="Targets" — the Targets group covers Location, DayTime, Radius, and other campaign-criterion types, so this deletes whatever criterion id is passed, not Location only. ids from get_entities('campaign_criteri…

Verify auth chain: token refresh + Customer Management GetUser round-trip.

List ALL advertiser accounts visible to the authenticated user (paged SearchAccounts under the hood; `truncated` is true only if the 1000-account safety cap was hit — raise MAX_PAGES if that ever happens for real).

Authenticated user + roles + configured account/customer ids.

Keyword ideas from seed keywords and/or a landing-page URL (Ad Insight GetKeywordIdeas). Scoped to the location/language/network configured via advertiser settings' keyword_research block (defaults: US/English/Owned&Operated+Syndicated).

Traffic estimates (clicks/impressions/CPC/cost) for candidate keywords at a given max CPC (defaults to the account's MS_ADS_MAX_CPC cap). Scoped to the location/language/network configured via advertiser settings (see discover_keywords).

Account recommendations (MS Ad Insight GetRecommendations). recommendation_type is passed through as-is to MS — live probing found the API rejects a null type but every documented RecommendationType enum value also faulted (607, account/feature gating, not a code issue); pass whatever type MS has en…

Draft applying an MS recommendation (mutates the account — rails apply).

Draft dismissing an MS recommendation.

Draft new keywords under an ad group — created Paused. keywords: [{text, match_type: Broad|Phrase|Exact, bid: optional float}]. Blocklist (settings-configured blocked_terms) + bid cap (MS_ADS_MAX_CPC) enforced.

Draft a keyword CPC bid change (MS_ADS_MAX_CPC cap enforced). Allowed ONLY when the ad group's effective bid strategy is in the MANUAL_BIDDING allowlist (rails.py). Pre-rejected for Smart Bidding: UpdateKeywords silently ignores Bid there instead of erroring (live-verified — empty PartialErrors, bid…

Draft keyword deletion (irreversible — pause_entity is the reversible lever).

Draft an image upload to the account media library (for image extensions / PMax asset groups). Returns media id on apply. PNG/JPEG.

Campaign-level negatives + ALL shared negative keyword lists (with items and campaign associations). Always call before recommending/adding negatives.

Draft negatives. scope: campaign | ad_group | shared_list. keywords: [{text, match_type: Phrase|Exact}]. Checks existing negatives first and skips duplicates (check-existing-lists-first rule). Blocklist NOT applied — negating a settings-blocked term is desired. scope='ad_group' REQUIRES campaign_id …

Draft negative removal by id. scope: campaign | ad_group | shared_list. keyword_ids come from get_negative_keywords. scope='ad_group' REQUIRES campaign_id for consistency with add_negative_keywords — validation only, DeleteNegativeKeywordsFromEntities has no parent field per WSDL.

Draft a Performance Max campaign + first asset group — created PAUSED. time_zone defaults to EasternTimeUSCanada (US-centric default) — override for other markets. target_cpa is required by default (require_pmax_target_cpa setting, default true) — never create PMax without a target; removing one lat…

Draft a portfolio bid strategy (account library, shared across campaigns). strategy_type: MaxConversions | MaxClicks | TargetImpressionShare. Returns a draft; apply with confirm_and_apply.

Ad extensions. campaign_id=None: full account library (sitelinks, callouts, structured snippets...). campaign_id set: only extensions associated with that campaign.

Conversion goals (nil ids returns all goals of the given types).

Disapproved ads + keywords in an ad group (editorial review failures).

Draft PERMANENT deletion of campaign | ad_group | keyword | ad. Irreversible — prefer pause_entity. ad_group needs parent_id=campaign id; keyword/ad need parent_id=ad group id.

Campaign performance (impressions/clicks/spend/conversions/CPA).

Per-ad performance.

Per-keyword performance incl. QualityScore.

Geographic performance.

Search query report.

Arbitrary report (replaces Google run_gaql for metrics pulls). report_type = exact v13 request type name e.g. 'AgeGenderAudienceReportRequest'.

REPLACE a campaign's ad schedule. week = 7 dicts {day, from_hour, to_hour} (0-23 hour clock; to_hour is the hour service stops, e.g. to_hour=22 serves until 22:00). MUST cover all 7 days — a campaign with any DayTime rows serves only inside them, so a partial week silently narrows delivery. Deletes …

Draft a pause. entity_type: campaign | ad_group | keyword | ad. keyword/ad need parent_id = ad group id; ad_group needs parent_id = campaign id.

Draft an enable (Status=Active). Same shape as pause_entity.