mcp-microsoft-ads
Connect an AI assistant to Microsoft Advertising for read-only reporting and research by default, with opt-in, preview-first write operations.
Run performance reports across campaigns, ads, keywords, search terms, geo, devices, conversion goals, revenue, impression share, and custom date ranges.
Check account health, list accounts, inspect campaigns/ad groups/keywords/ads/asset groups/campaign criteria, and review negative keywords, extensions, conversion goals, and policy issues.
Research keywords with ideas, traffic forecasts, geo-target search, and Microsoft recommendations when available.
When writes are enabled, create paused campaigns/ads/keywords, update budgets/bids/statuses/target CPA, pause/enable/remove entities, and replace ad schedules.
Manage negatives, location exclusions, sitelinks/callouts/structured snippets, image assets, custom audiences, audience targeting, and conversion goals.
Apply or dismiss Microsoft recommendations only with an additional separate opt-in flag.
Every write is draft-first via
confirm_and_apply, with spend ceilings, Smart Bidding fail-closed guards, and a JSONL audit log.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-microsoft-ads How did my Microsoft Ads campaigns perform last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-microsoft-ads
Unofficial — not affiliated with, endorsed by, or supported by Microsoft. This is a third-party MCP (Model Context Protocol) server for Microsoft Advertising. "MCP" is the open protocol that lets an AI assistant (Claude, or any other MCP client) call tools against a real system — here, your Microsoft Ads account.
In plain terms: this connects an AI assistant such as Claude to your Microsoft Advertising (Bing Ads) account, so you can ask questions about performance in plain English and, if you choose to allow it, have the assistant make changes for you. It starts read-only. Changes are something you switch on, and every change is previewed before it happens.
48 tools cover reporting, keyword research, and campaign, ad group, keyword, negative-keyword, location, ad-schedule, extension, image, audience, and conversion-goal management.
What you can ask
Once it is connected, talk to your assistant normally. For example:
"How did each campaign do over the last 30 days? Show spend, conversions and cost per conversion."
"Which search terms spent money last month without converting? Check them against my existing negative keyword lists and suggest only new negatives."
"Split last month's conversions by conversion goal for each campaign."
"What was my impression share last quarter, and did I lose more to budget or to rank?"
"Find keyword ideas for 'emergency plumber' and estimate clicks at a $12 bid."
"Are any ads or keywords disapproved?"
"Pause the ad group called Test, and show me the change before you make it." (needs changes switched on, see Turning on changes)
Every report comes back with a source note: the account, the report type, the date range, the columns pulled, and how conversions were counted.
Related MCP server: Social MCP
Quick start
You need a Microsoft Advertising account and about 20 minutes, most of it on Microsoft's side. All commands below go in a terminal (the Terminal app on a Mac, PowerShell on Windows).
Install uv, a small free tool that downloads and runs this server for you. One command, from https://docs.astral.sh/uv/getting-started/installation/.
Get two things from Microsoft: a developer token and an "app registration". docs/setup.md steps 2 and 3 walk through both, click by click. This is the slow part, and you only do it once.
Run the guided setup. It asks for the values from step 2, opens the Microsoft sign-in, and saves everything in a private file on your computer:
uvx --from git+https://github.com/wvuhskr/mcp-microsoft-ads mcp-microsoft-ads setupConnect your assistant. Setup ends by printing a short block of text. Paste it into your assistant's connector settings (MCP client configuration shows where) and restart the assistant.
Check it. Ask the assistant: "Run a Microsoft Ads health check and list my accounts." Confirm the account name and currency are the ones you expect.
If the sign-in ever stops working (Microsoft asks for a fresh sign-in from time to
time), run the same command with reauth in place of setup.
The tools
You never call these by name; the assistant picks them. The list is here so you know what is possible.
Look, never change (always available)
Tool | What it does |
| Confirm the connection and which account you are in |
| Ready-made performance reports for the last 7, 14 or 30 days |
| What people actually typed before clicking |
| Performance by country, state, metro area and city |
| Build-your-own report: any Microsoft report, any columns, any dates. |
| Current settings of campaigns, ad groups, keywords, ads, asset groups, schedules and locations |
| Campaign negatives plus every shared negative list |
| Extensions, conversion goals, disapproved ads and keywords |
| Keyword ideas and traffic estimates |
| Find a location to target or exclude |
| Microsoft's recommendations (not available on every account) |
Make changes (only when you switch changes on; each one is previewed first)
Tool | What it does |
| Carries out a previewed change. Nothing changes without it |
| Pause, enable or delete a campaign, ad group, keyword or ad |
| Budget, status, target cost per conversion, manual bids |
| New campaigns (always created paused) and shared bid strategies |
| New ads and keywords (keywords created paused) |
| Negatives on a campaign, ad group or shared list; duplicates are skipped |
| Replace a campaign's ad schedule |
| Location exclusions |
| Ad extensions |
| Add an image to the account's library |
| Remarketing lists and audience targeting |
| Conversion goals |
| Act on Microsoft's recommendations (extra switch required) |
Why "safety-first"
Every mutating tool is off by default. Turning writes on is one env var, and even then every write goes through the same layered gate before a single call reaches Microsoft's API:
MS_ADS_ENABLE_WRITES=true— without it, every write tool refuses to run. Out of the box this is a read-only server.Draft → confirm. A write tool never mutates on its own call. It returns a preview (a
draft_idand exactly what would change); nothing lands until you — or your MCP client — callsconfirm_and_apply(draft_id).Spend ceilings. Draft creation and apply both reject amounts above
MS_ADS_MAX_DAILY_BUDGET(default 1000) orMS_ADS_MAX_CPC(default 50), in the account's own currency, not USD.Smart Bidding fail-closed guards. Bid/adjustment writes are allowlisted to manual bidding strategies (
ManualCpc,EnhancedCpc,ManualCpv,ManualCpm,ManualCpa); an unrecognized or automated strategy (MaxConversions,TargetCpa,TargetRoas, …) is refused rather than assumed safe.JSONL audit log. Every draft and every apply is appended to a local, append-only JSONL file — a plain-text paper trail of what this server actually did.
Backed by 420+ offline tests (no live API calls) that exercise the rails, the SOAP plumbing quirks, and the draft/confirm lifecycle against fakes.
Be honest about what "draft → confirm" is not
Draft → confirm is a preview gate against single-call accidents — a typo in a bid,
a copy-paste mistake, calling the wrong tool. It is not human-approval access
control: the same MCP client that created the draft can call confirm_and_apply
immediately afterward, with no human in the loop required by the server. If you want
a human to review every write, that has to be enforced by your own workflow (a
separate approval step, a human-only client, etc.) — this server doesn't do it for you.
One write is called out separately because the layered story above can't fully bound
it: apply_recommendation hands off to a Microsoft-decided mutation — you preview
only the recommendation ID, not the change itself, so the actual monetary effect isn't
something this server's spend ceilings can check in advance. It's kept (Microsoft's
recommendations can be useful), loudly labeled as the exception it is, and gated
behind both MS_ADS_ENABLE_WRITES and its own separate flag,
MS_ADS_ALLOW_APPLY_RECOMMENDATION — so turning on writes generally does not turn
this one on.
What this server does not do
No Quality Score diagnostics.
No automatic retry/backoff on transient API failures (a failed call fails; you retry).
Built on Microsoft's SOAP Bing Ads SDK, which Microsoft has announced end-of-life — see below.
SOAP end-of-life and the REST roadmap
This server is built on the bingads SOAP SDK. Microsoft has announced that SOAP is
end-of-life on 2027-01-31, and recommends migrating before 2026-10-01 (new
API features ship REST-only from then). See Microsoft's
Migrate to REST API
guide and the
Python SDK SOAP-to-REST migration guide.
Porting this server's tools to REST is the roadmap item — SOAP still works today and
isn't going away until the EOL date, but don't plan around it long-term.
How this compares
write access | write safety layer | notes | |
mcp-microsoft-ads (this project) | yes, opt-in | draft→confirm + spend ceilings + Smart-Bidding guards + audit log | SOAP today, REST planned |
— | — | see their repo for current scope | |
bit-of-a-shambles Bing Ads MCP server | — | — | see that project's repo for current scope |
CData Microsoft Ads MCP connector | read-only | n/a | no write path |
Microsoft's official hosted MCP | — | — | see Microsoft's docs for current scope |
Comparison last checked 2026-08-24. This project doesn't claim to know the exact current feature set of the other rows beyond what's read-only vs. not — check each project's own repo/docs for details. The differentiators above (opt-in writes, two-phase draft→confirm, spend ceilings, Smart-Bidding fail-closed guards, JSONL audit log, 420+ offline tests) are what this project is built around.
Install for development
Most people should use the Quick start instead. To work on the code:
git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
cd mcp-microsoft-ads
python3 -m venv .venv # requires Python >= 3.12
.venv/bin/pip install -e ".[dev]"In a clone, .venv/bin/mcp-microsoft-ads setup runs the same guided setup.
Credentials
Credentials live outside the repo, in a YAML file (default
~/.mcp-microsoft-ads/credentials.yaml, override with MS_ADS_CREDENTIALS_PATH):
developer_token, client_id, client_secret, refresh_token, customer_id,
account_id, tenant.
The six static fields (everything except refresh_token) can instead be set as
MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET,
MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT env vars — env wins over the
file when both are present. refresh_token is file-only: Microsoft rotates it on
every use, and a rotated token has to be persisted somewhere for the next run, which
an env var can't do. The server persists each rotation back to the credentials file
atomically (a .bak is kept). Both replacement files are created with
owner-only access before any credential content is written. Rotation changes only
the refresh-token value; unusual YAML aliases or block values may be rewritten
without their original comments to preserve the credential values safely.
Image upload safety
upload_image_asset accepts valid PNG or JPEG files only. Local safety limits
are 5 MiB per file and 20 million pixels; these are this server's limits, not
Microsoft account limits. Animated and malformed images are rejected locally.
The preview includes a SHA-256 digest, a fingerprint of the file's contents.
Changing the file after preview requires a new draft. Validated bytes are uploaded
unchanged, including image metadata, so use assets intended for advertising.
Supported tool library versions
The Model Context Protocol (MCP) library must be at least 1.30.0 and below 3. The automated checks test the oldest supported version and the current version. Intentional safety refusals and partial-write warnings remain visible to the assistant in both library generations; unexpected errors retain the library's normal handling.
Turning on changes
Out of the box the server can only look. To let the assistant make changes:
Confirm the account first. While still read-only, have the assistant run
health_check, thenlist_accountsandget_account_info. Check the account ID, name and currency against the account you mean. The spending limits below are enforced in that account's currency.Add the switch to the connector block (see the next section) and restart the assistant:
MS_ADS_ENABLE_WRITESset totrue. Optionally lower the spending limitsMS_ADS_MAX_DAILY_BUDGETandMS_ADS_MAX_CPCto fit your account.Optional house rules. Copy advertiser.example.yaml to
~/.mcp-microsoft-ads/advertiser.yamlto ban words from ad copy, set your website, and keep the "no Performance Max campaign without a target" rule on.
MCP client configuration
This is the block the guided setup prints. It tells your assistant how to start the server.
Claude Desktop: Settings > Developer > Edit Config opens
claude_desktop_config.json. Claude Code: put it in .mcp.json in your project.
{
"mcpServers": {
"microsoft-ads": {
"command": "uvx",
"args": ["--from", "git+https://github.com/wvuhskr/mcp-microsoft-ads", "mcp-microsoft-ads"]
}
}
}With changes switched on, the same block gains an env section:
{
"mcpServers": {
"microsoft-ads": {
"command": "uvx",
"args": ["--from", "git+https://github.com/wvuhskr/mcp-microsoft-ads", "mcp-microsoft-ads"],
"env": { "MS_ADS_ENABLE_WRITES": "true", "MS_ADS_MAX_DAILY_BUDGET": "500" }
}
}
}If your assistant reports it cannot find uvx, replace "uvx" with the full path
that which uvx (Mac/Linux) or where uvx (Windows) prints in a terminal. Working
from a clone instead: use "command": "/full/path/to/mcp-microsoft-ads/.venv/bin/mcp-microsoft-ads"
with no args.
Several assistant sessions at once
Each open assistant session starts its own copy of this server, and they can all share
one credentials file on the same computer. Microsoft issues a new refresh_token on
each refresh but does not revoke the earlier ones when it does
(Microsoft's refresh-token documentation),
so when two sessions refresh close together the newer token simply replaces the other
on disk. Each write is atomic, so the file always holds one complete, working token.
A file with no usable token at all is still refused rather than overwritten.
Environment variables
Var | Default | Purpose |
|
| credentials file location |
|
| optional advertiser settings (blocked terms, advertiser domain, keyword-research defaults) — missing file means defaults |
|
| JSONL audit log location |
|
| master switch for all mutating tools |
|
| second, separate switch required (in addition to |
|
| daily-budget rail ceiling, in the account's own currency |
|
| bid/tCPA rail ceiling, in the account's own currency |
|
| how long a draft stays valid before |
| — | the six static credential fields; env wins over the credentials file when both are set |
Currency note: MS_ADS_MAX_DAILY_BUDGET and MS_ADS_MAX_CPC are compared directly
against amounts in the account's own currency, not converted to or from USD. A 1000
ceiling means 1000 units of whatever currency the account is denominated in.
Test / lint
.venv/bin/python -m pytest -q # offline test suite, 420+ tests, no live API calls
.venv/bin/python -m ruff check . # lintDocumentation
docs/setup.md — Azure app registration, developer token, full bootstrap.
advertiser.example.yaml — optional house rules, with comments.
SECURITY.md — how to report a vulnerability.
CHANGELOG.md — release history.
License and support
MIT-licensed — see LICENSE. This is a best-effort, unpaid open-source project: no SLA, no guaranteed response time. Issues are watched and triaged on a best-effort basis.
Available Tools
48 toolsadd_audience_targetingA
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_pct is allowed ONLY when the campaign's effective bid strategy is in the MANUAL_BIDDING allowlist (rails.py); rejected for Smart Bidding, any other/unrecognized strategy, or when the strategy can't be determined at all (fail closed — standing no-%-adjustments-on-auto-bidding rule).
Live-verified 2026-07-30 (the AddCampaignCriterions write path, CriterionType= "Audience"); the read-side fault seen earlier is GET-only and doesn't apply here.
Inputs: audience_id (required), campaign_id (required), audience_type, bid_adjustment_pct.
add_negative_keywordsA
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 (the parent campaign) — MS's read API hard-faults for AdGroup scope without it.
Live-verified 2026-07-28 at ad_group scope, including the duplicate-check read; campaign scope not separately smoked.
Inputs: scope (required), keywords (required), entity_id (required), campaign_id.
apply_recommendationA
Draft applying an MS recommendation (mutates the account — rails apply).
NOT live-verified — every RecommendationType faults 607 InvalidOpportunityType on the development account (account-level gating). Fakes only.
Also gated by MS_ADS_ALLOW_APPLY_RECOMMENDATION (rails.py), in addition to the global MS_ADS_ENABLE_WRITES — its monetary effect can't be bounded by the budget/bid caps, so it needs its own opt-in on top of the general write gate.
Inputs: recommendation_id (required).
confirm_and_applyA
Execute a previously drafted write. The ONLY path that mutates the account.
Live-verified from 2026-07-28 onward — the only mutation path in this server; every live write in the project flowed through it.
Inputs: draft_id (required).
create_calloutsB
Draft callout extensions (max 25 chars each).
Live-verified 2026-07-30.
On a mid-apply failure (association raises after the library add landed) the error carries every landed ID (extension_ids) — reconcile account state before retrying (a retry re-runs ALL steps, including re-adding the extensions).
Inputs: texts (required), campaign_id (required).
create_conversion_actionA
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="Contains")
Event: action_expression (matched with ActionOperator="Contains"; category/label expressions are out of scope here)
Duration: minimum_duration_seconds goal_category (ConversionGoalCategory enum) is REQUIRED live even though the WSDL marks it optional — omitting it faults "InvalidGoalCategory" (3347). Defaults to "Other", the only value live-verified valid across all three goal types (live probe); PageView also works on Url/Event but faults InvalidCategoryForGoalType (3349) on Duration. A category already claimed by an ACTIVE MS auto-created goal on the same UET tag faults SameCategoryAndTagNotAllowedForAutoGoalAndManualGoal (5667) — observed on Url goals only; the live acceptance matrix never exercised Event or Duration for this collision. The fault is keyed on category+tag rather than goal type, so it plausibly extends to Event/Duration too, but that's inference, not a tested fact — account state decides, not goal type. Lead-gen-meaningful values: SubmitLeadForm, BookAppointment, RequestQuote, Contact. NOTE: OfflineConversion goals are deliberately not created by this tool — create them in the MS Ads UI instead — because accounts that feed offline conversions from an external upload pipeline risk double-counting. ONE-WAY DOOR: there is no DeleteConversionGoals operation on this API (verified against the WSDL — every other entity family has a Delete*, this one doesn't) and UpdateConversionGoals(Status="Deleted") silently no-ops (partial_errors=[], goal reads back Active still) — so a created goal cannot be deleted. The only real levers are Status="Paused" and ExcludeFromBidding=True (both verified by read-back); full removal requires the MS Ads UI.
Live-verified 2026-07-30.
Inputs: name (required), value, goal_type, goal_category, +3 more.
create_custom_audienceB
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 set. A whitespace-only url_contains is rejected outright (not treated as omitted).
Live-verified 2026-07-30.
Inputs: name (required), description (required), url_contains, membership_duration_days.
create_pmax_campaignA
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 later explodes impressions (hard rule observed on a live Google Ads account). Set require_pmax_target_cpa false in advertiser settings to allow a no-target MaxConversions campaign instead. Images are REQUIRED (upload via upload_image_asset first). Each image_media_ids entry must already be in the account media library with MediaType Image1x1 or Image191x100; GenericImage, Image4x1, unknown types, and absent ids raise. Aborts the asset-group add if the campaign add fails. Returns a draft; apply with confirm_and_apply.
Live-verified 2026-07-30 — with an explicit target_cpa: campaign + asset group created and read back with both images carrying the correct per-image SubType; ImageAsset.Id = media id write-proven. NOT live-verified — the require_pmax_target_cpa=false / no-target_cpa path: only exercised against fakes, never run against the live API through this tool. NOT live-verified with non-default time_zone values.
On a mid-apply failure (asset group add raises after the campaign landed) the error carries every landed ID (campaign_ids) — reconcile account state before retrying (a retry re-runs ALL steps, including re-creating the campaign).
Inputs: name (required), final_url (required), headlines (required), daily_budget (required), +6 more.
create_portfolio_bidding_strategyA
Draft a portfolio bid strategy (account library, shared across campaigns). strategy_type: MaxConversions | MaxClicks | TargetImpressionShare. Returns a draft; apply with confirm_and_apply.
Live-verified 2026-07-30.
Inputs: name (required), strategy_type (required), target_cpa.
create_structured_snippetsB
Draft a structured snippet (header must be an MS-supported header, e.g. 'Services'; 3+ values required).
Live-verified 2026-07-30.
On a mid-apply failure (association raises after the library add landed) the error carries every landed ID (extension_ids) — reconcile account state before retrying (a retry re-runs ALL steps, including re-adding the extension).
Inputs: header (required), values (required), campaign_id (required).
describe_reportA
Look up what run_report accepts — call this before run_report instead of guessing names. No argument: every report type. With a report_type (e.g. 'CampaignPerformanceReportRequest'): every valid column name for it. Read offline from Microsoft's own API definition shipped with the SDK; makes no API call.
Inputs: report_type.
discover_keywordsB
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).
Inputs: url, seed_keywords.
dismiss_recommendationB
Draft dismissing an MS recommendation.
NOT live-verified — same 607 gate as apply_recommendation. Fakes only.
Inputs: recommendation_id (required).
draft_campaignB
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.
Live-verified 2026-07-30 (AddCampaigns create path, proven twice). NOT live-verified with non-default language values.
Inputs: name (required), daily_budget (required), campaign_type (required), language, +1 more.
draft_keywordsA
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.
Live-verified 2026-07-28 (one paused keyword added to a z. ad group).
Inputs: keywords (required), ad_group_id (required).
draft_responsive_search_adB
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/description/path. MS RSAs have no per-ad paused state on create — if isolation is needed, pause the parent ad group first; preview warns when it's Active (new ad serves once approved).
Live-verified 2026-07-28 — ad created in a z. ad group, read back with Type="ResponsiveSearch".
Inputs: final_url (required), headlines (required), ad_group_id (required), campaign_id (required), +3 more.
draft_sitelinksA
Draft sitelinks on a campaign. sitelinks: [{text, url, description1?, description2?}]. Copy claims must be site-verified (the advertiser's website).
Live-verified 2026-07-30.
On a mid-apply failure (association raises after the library add landed) the error carries every landed ID (extension_ids) — reconcile account state before retrying (a retry re-runs ALL steps, including re-adding the extensions).
Inputs: sitelinks (required), campaign_id (required).
enable_entityC
Draft an enable (Status=Active). Same shape as pause_entity.
Live-verified 2026-07-28: ad_group branch (same probe as pause_entity). NOT live-verified: campaign/ad/keyword branches (fixed by analogy only).
Inputs: entity_id (required), entity_type (required), parent_id.
exclude_geo_targetB
Draft a location EXCLUSION on a campaign. location_id from search_geo_targets.
Live-verified 2026-07-30.
Inputs: campaign_id (required), location_id (required).
get_account_infoB
Authenticated user + roles + configured account/customer ids.
Inputs: no named parameters.
get_ad_performanceA
How each ad did, day by day: impressions, clicks, spend, conversions, click-through rate, with its campaign and ad group.
days must be 7, 14, or 30 (one row per day). For any other date range, other columns, or totals instead of daily rows, use run_report.
Inputs: days.
get_campaign_performanceA
How each campaign did, day by day: impressions, clicks, spend, conversions, cost per conversion, click-through rate, average cost per click.
days must be 7, 14, or 30 (one row per day). For any other date range, other columns, or totals instead of daily rows, use run_report.
Inputs: days.
get_conversion_actionsD
Conversion goals (nil ids returns all goals of the given types).
Inputs: no named parameters.
get_entitiesA
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 reads as None on MS — effective strategy lives on ad_groups (BiddingScheme.InheritedBidStrategyType).
Inputs: entity (required), ids, parent_id.
get_geo_performanceA
Where the clicks came from, day by day: country, state, metro area, city, with impressions, clicks, spend, conversions.
days must be 7, 14, or 30 (one row per day). For any other date range, other columns, or totals instead of daily rows, use run_report.
Inputs: days.
get_keyword_forecastsB
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).
Inputs: keywords (required), max_cpc, match_type.
get_keyword_performanceA
How each keyword did, day by day: match type, impressions, clicks, spend, conversions, cost per conversion, Quality Score.
days must be 7, 14, or 30 (one row per day). For any other date range, other columns, or totals instead of daily rows, use run_report.
Inputs: days.
get_negative_keywordsA
Campaign-level negatives + ALL shared negative keyword lists (with items and campaign associations). Always call before recommending/adding negatives.
Inputs: campaign_id.
get_policy_issuesA
Disapproved ads + keywords in an ad group (editorial review failures).
Inputs: ad_group_id (required).
get_search_termsA
What people actually typed before clicking (search terms report), day by day, with the keyword that matched and impressions, clicks, spend, conversions. The usual starting point for finding wasted spend and negative-keyword candidates.
days must be 7, 14, or 30 (one row per day). For any other date range, other columns, or totals instead of daily rows, use run_report.
Inputs: days.
health_checkA
Verify auth chain: token refresh + Customer Management GetUser round-trip.
Inputs: no named parameters.
list_accountsA
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).
Inputs: no named parameters.
list_extensionsA
Ad extensions. campaign_id=None: full account library (sitelinks, callouts, structured snippets...). campaign_id set: only extensions associated with that campaign.
Inputs: campaign_id.
list_recommendationsB
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 enabled for this account.
NOT live-verified — 607-gated on the development account, as above.
Inputs: ad_group_id, campaign_id, recommendation_type.
pause_entityB
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.
Live-verified 2026-07-28: ad_group branch (Paused→Active→Paused on a z. ad group, read-back verified). NOT live-verified: campaign/ad/keyword branches (fixed by analogy only).
Inputs: entity_id (required), entity_type (required), parent_id.
remove_entityA
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.
Live-verified: ad branch 2026-07-28, campaign/keyword branches 2026-07-30. NOT live-verified: ad_group branch (fixed by analogy only).
Inputs: entity_id (required), entity_type (required), parent_id.
remove_extensionA
Draft removal: disassociate from campaign, then delete from library.
Live-verified 2026-07-30.
If the disassociation itself (step 1) comes back with a batch error, nothing landed — the apply aborts and the delete is never attempted (aborted=... in the result), nothing to reconcile.
On a mid-apply failure (delete raises after disassociation landed) the error carries what landed (disassociated=True, deleted=False) — reconcile account state before retrying (a retry re-runs ALL steps, including re-disassociating).
Inputs: campaign_id (required), extension_id (required).
remove_geo_targetA
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_criterions', parent_id=campaign_id).
Live-verified 2026-07-30.
Inputs: campaign_id (required), criterion_id (required).
remove_keywordsC
Draft keyword deletion (irreversible — pause_entity is the reversible lever).
Live-verified 2026-07-28.
Inputs: ad_group_id (required), keyword_ids (required).
remove_negative_keywordsA
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.
Live-verified 2026-07-28 at ad_group scope; campaign scope not separately smoked.
Inputs: scope (required), entity_id (required), keyword_ids (required), campaign_id.
run_reportA
Build-your-own report: any Microsoft Ads report type, any columns, any date range. Use describe_report to look up valid report types and column names.
Common recipes (report_type: useful columns beyond Impressions/Clicks/Spend):
Totals for a period: any type with aggregation="Summary" and NO TimePeriod column.
Conversions split by goal: CampaignPerformanceReportRequest with Goal, GoalType, Conversions, Revenue (also valid on ad group / keyword / search-term reports).
Revenue and return: CampaignPerformanceReportRequest with Revenue, ReturnOnAdSpend.
Impression share and why it was lost: CampaignPerformanceReportRequest with ImpressionSharePercent, ImpressionLostToBudgetPercent, ImpressionLostToRankAggPercent.
Device split: add DeviceType to a campaign / ad group / keyword report.
Whole account: AccountPerformanceReportRequest with AccountName, CurrencyCode.
Performance Max asset groups: AssetGroupPerformanceReportRequest.
Age and gender: AgeGenderAudienceReportRequest with AgeGroup, Gender. Goal / GoalType cannot share a report with impression-share columns (the API faults RestrictedColumnCombinations, 2064) — run those as two reports. Recipes live-verified 2026-11-17.
aggregation: "Daily" (default) works with any column set; Weekly / Monthly / DayOfWeek / HourOfDay also need the TimePeriod column. "Summary" is only valid when columns exclude TimePeriod — the live API raises InvalidTimePeriodColumnForSummaryReport otherwise.
Dates: days must be 7, 14, or 30. Or pass start_date/end_date (YYYY-MM-DD, both or neither) for an explicit range of any length. Live-verified 2026-08-14 (106-day AccountPerformance custom-range pull).
Inputs: columns (required), report_type (required), days, end_date, +2 more.
search_geo_targetsA
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.
Inputs: query (required).
set_campaign_scheduleA
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 existing DayTime criterions then adds the new set. Returns a draft; apply with confirm_and_apply.
Live-verified 2026-07-30 including the REPLACE delete path (7 rows deleted/7 added, read-back verified).
On a mid-apply failure (add or the verify readback raises after the existing schedule was deleted) the error carries every landed ID (deleted_criterion_ids, added_criterion_ids) — reconcile account state before retrying (a retry re-runs ALL steps, including re-deleting whatever the previous attempt left).
Inputs: week (required), campaign_id (required).
set_conversion_action_primary_statusB
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).
Live-verified 2026-07-30, both directions.
Inputs: goal_id (required), primary (required), campaign_id (required).
update_ad_groupA
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 (rails.py) — same fail-closed guard as update_keyword_bid; MS silently ignores fixed bids under Smart Bidding. Returns draft; apply with confirm_and_apply (policy rails re-checked at apply).
NOT live-verified through this tool itself. The underlying blank()-built UpdateAdGroups call IS live-proven (2026-07-28, Status flip on a z. ad group via pause/enable_entity); the cpc_bid / target_cpa branches have never run live.
Inputs: ad_group_id (required), campaign_id (required), status, cpc_bid, +1 more.
update_campaignA
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.
NOT live-verified through this tool itself. The underlying blank()-built UpdateCampaigns call IS live-probed (2026-07-30, DailyBudget-only change), via the same pattern live-proven through status.py's ad_group Status flip (2026-07-28), not through update_ad_group itself.
Inputs: campaign_id (required), status, target_cpa, daily_budget.
update_keyword_bidA
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 unchanged on read-back), so this must be caught before the call, not after. Also rejected, fail closed, for any other unrecognized strategy or when the effective strategy can't be determined at all.
NOT live-verified for a landed bid change — the manual-bidding write path has never run live (no manual-bidding ad group exists on the development account).
Inputs: bid (required), keyword_id (required), ad_group_id (required).
upload_image_assetA
Draft an image upload to the account media library (for image extensions / PMax asset groups). Returns media id on apply. Valid PNG/JPEG only, at most 5 MiB and 20 million pixels (local safety limits). The file must remain byte-identical between preview and apply; otherwise create a new draft.
media_type is the image's aspect ratio, one of:
Image1x1: square (e.g. 1200x1200)
Image191x100: 1.91:1 landscape (e.g. 1200x628)
GenericImage
Image4x1
Live-verified 2026-07-30, after fixing two live faults (MediaType is an aspect-ratio label; the AddMedia response comes back unwrapped — both noted above). AddMedia also dedupes byte-identical images: re-uploading returns the existing media id.
Inputs: file_path (required), media_type (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Most tools name a distinct resource+action pair, and the descriptions actively disambiguate (run_report vs the get_*_performance shorthands, remove_entity warning to prefer pause_entity, create_conversion_action vs set_conversion_action_primary_status). A few genuine overlaps remain: remove_keywords vs remove_entity(keyword), pause_entity vs update_campaign's status field, and draft_campaign(campaign_type=PerformanceMax) vs create_pmax_campaign.
The dominant pattern is verb_noun (pause_entity, get_entities, add_negative_keywords, list_accounts), but the write surface mixes draft_* (draft_campaign, draft_keywords, draft_sitelinks, draft_responsive_search_ad) with create_* for tools that also only return drafts (create_callouts, create_custom_audience, create_portfolio_bidding_strategy). The draft/create distinction carries no semantic meaning yet splits otherwise identical operations, and get_/list_/search_/describe_ are used somewhat loosely.
48 tools is well past the 25+ threshold and the surface is inflated by fine-grained per-entity reads (get_campaign_performance, get_ad_performance, get_keyword_performance, get_geo_performance, get_search_terms) that run_report already generalizes. Each tool is defensible individually, but the draft/apply split and per-entity granularity make the set heavy relative to what an agent can reliably select from.
Coverage is broad — campaigns, keywords, ads, negatives, extensions, geo, audiences, conversions, bidding strategies, recommendations, reporting, forecasts. However there is no ad-group creation tool at all, so an agent can create a campaign (draft_campaign) but cannot build a Search campaign's ad groups from scratch, and shared negative keyword list creation is also missing (add_negative_keywords only references shared_list scope).
Maintenance
Related MCP Connectors
Manage Google, Microsoft, ChatGPT and Meta Ads safely: previewed, logged, revertible changes.
Connect authorized ad accounts to AI assistants for audits, reporting, and approval-gated changes.
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Connect your AI to Meta, Google and LinkedIn ads: read stats, draft changes, publish on approval.
1
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants to Microsoft Advertising (Bing Ads) accounts so they can query performance, pull search advertising reports, and create or optimize campaigns, ad groups, keywords, audiences, and conversion tracking through natural language. Write actions are available but new campaigns start paused and deletes stay off by default.MIT
- AlicenseBqualityCmaintenanceEnables AI assistants and agents to read analytics and manage advertising across Google Ads, Google Analytics 4, and Meta Ads through natural language, with preview-confirm guardrails and configurable account and budget limits.21MIT

Orphex MCPofficial
AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query advertising spend, ROAS, campaigns, pacing and anomalies across many ad, analytics and commerce platforms, and to make approval-first changes such as pausing campaigns or adjusting budgets after a preview.2Apache 2.0- AlicenseBqualityBmaintenanceEnables AI assistants to run a Google Ads account through conversation, covering reporting and GAQL queries, campaign and Performance Max creation, ads, keywords, budgets and MCC hierarchies. Spend-affecting actions return a cost preview and require explicit confirmation, with optional hard spend limits enforced even after approval.47Apache 2.0