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-msads show me my Bing Ads campaigns from last week with clicks and cost"
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.
Microsoft Advertising (Bing Ads) MCP server — campaigns, keywords, reporting, keyword planning, bulk export, and billing via natural language.
Built on the REST/JSON API. Microsoft stops shipping features to the SOAP API on 2026-10-01 and removes it entirely on 2027-01-31.
Microsoft ships an official Microsoft Advertising MCP server, but it is hosted and read-only. Of the eight open-source alternatives, none has more than four stars, half are built on the dying SOAP API, and several ship live write access with no tests at all.
Nothing in the field covers Customer Billing. One server each covers Bulk and
Ad Insight. mcp-msads covers all three, can write, and is tested.
Related MCP server: Bing Ads MCP Server
claude mcp add msads --scope user --transport stdio \
-e MSADS_DEVELOPER_TOKEN=... \
-e MSADS_CLIENT_ID=... \
-e MSADS_CLIENT_SECRET=... \
-e MSADS_TOKEN_FILE=/absolute/path/to/msads-token.json \
-- npx -y mcp-msads@latestMicrosoft Advertising needs three things, and there is no app-only path — a user must consent once through a browser.
Sign in at https://ads.microsoft.com/cc/Settings/DevSettings with Super Admin credentials and request one.
For the sandbox, skip this: the universal token BBD37VB98 works for everyone.
Set MSADS_ENVIRONMENT=sandbox and it is used automatically.
https://portal.azure.com → Microsoft Entra ID → App registrations → New registration.
Supported account types: "Accounts in any organizational directory and
personal Microsoft accounts". Anything narrower fails against /common.
Platform: Web. Redirect URI: http://127.0.0.1:31544/callback
Certificates & secrets → New client secret.
The redirect URI must match byte-for-byte. If you pass a custom --port,
register the exact http://127.0.0.1:<port>/callback URI that setup prints.
Register a Web app with a secret, not a public/native client. A public-client refresh token is bound to the device that granted it and fails with
invalid_granton any other host.
MSADS_CLIENT_ID=... MSADS_CLIENT_SECRET=... bun run setup
# or, without a checkout:
MSADS_CLIENT_ID=... MSADS_CLIENT_SECRET=... npx -y mcp-msads setupmcp-msads setup --help lists the flags (--port, --out, --allow-in-repo)
without starting authorization; unknown flags are rejected.
This opens a browser, catches the IPv4-loopback callback, and writes a mode-0600
refresh-token file under the platform config directory (mcp-msads/msads-token.json).
Point MSADS_TOKEN_FILE at the printed path, or copy the refresh token into
MSADS_REFRESH_TOKEN. An explicit --out inside a Git checkout is rejected unless
--allow-in-repo is also supplied.
Prefer MSADS_TOKEN_FILE: refresh tokens rotate on every use, and the file lets
the server persist each rotation instead of holding it in memory only. Access
tokens are short-lived and are never persisted.
Microsoft Advertising accounts can be created with a Google sign-in, and for
sandbox that is often the only practical route — Microsoft-account sign-up
requires an outlook.com address.
A Google-owned user cannot be authenticated with a Microsoft token. The API
needs a Google OAuth token plus an IdentityProvider: Google header. Point the
server at Google and it handles the rest:
MSADS_IDENTITY_PROVIDER=google
MSADS_CLIENT_ID=<google client id>
MSADS_CLIENT_SECRET=<google client secret>Create that client at
https://console.cloud.google.com/apis/credentials → Create credentials →
OAuth client ID. For local use, choose Desktop app: Google accepts loopback
redirects on the temporary callback port without pre-registering each port. A
Web application client also works, but it must register the exact loopback
URI printed by setup (by default http://127.0.0.1:31544/callback). Then run
bun run setup as usual.
The Entra app registration is not used in this mode — a Microsoft app cannot authenticate a Google user. Everything downstream is unchanged: the same developer token, the same account permissions, the same tools.
Symptom of getting this wrong: authorization succeeds, then every API call returns error 105.
The three credentials split three ways, and the split matters.
Credential | Scope | Share it? |
| The application | Yes — it is a public identifier |
| The application | Yes, but as a real secret |
| The application | Yes — universal since July 2019, it works with any Microsoft Advertising user |
| One person | No. Each person runs |
One app registration and one developer token serve the whole team. Everyone puts the same three values in their environment, then authorizes individually:
bun run setup --out ~/.config/mcp-msads/token.jsonPer-person refresh tokens are the right design, not a limitation. Actions attribute to the real person in Microsoft Advertising's change history, one person leaving does not break everyone, and a password change or MFA prompt affects only that individual. A single shared refresh token collapses all three of those.
Before sharing a checkout or credential bundle that predates these safeguards, revoke its existing OAuth grant with the identity provider and run setup again. Deleting a local token file does not revoke the provider-side grant.
Account access is separate from all of this. A developer token grants no data access whatsoever — it only permits the application to call the API. Each colleague must also be invited to the Microsoft Advertising account itself, under Account settings → Users, with a role (Super Admin, Standard, Advertiser Campaign Manager, or Viewer). Up to 15 users per customer. Someone with perfect credentials and no invitation gets error 106.
The secret expires, and everyone breaks at once. Note the expiry when you create it. Rotating means issuing a new secret and redistributing it — existing refresh tokens keep working, since they are bound to the client id.
One registration covers both environments. Sandbox and production share
the same Entra app; what differs is the developer token (sandbox uses the
universal BBD37VB98) and the accounts themselves. Credentials are never
interchangeable between the two — mixing them produces error 105.
Sign up at https://sandbox.bingads.microsoft.com, set
MSADS_ENVIRONMENT=sandbox, and no developer token is needed. Note that ads
never serve, Ad Insight is heavily degraded, and only nine report types return
data.
81 tools. ⚠️ marks the destructive ones.
Collection reads return at most 200 rows by default and 5,000 at the hard limit.
Responses keep their domain result key and report showing, truncated, plus
total or discovered only when known; truncated results include narrowing or
pagination guidance. Bulk downloads retain at most 100,000 rows, archives are
bounded, and bulk uploads accept at most 100,000 records.
Tool | Purpose |
| List every Microsoft Advertising ad account this login can reach, each paired with the manager (customer) account that owns it. |
| Identity of the authenticated Microsoft Advertising user, including the customer roles and account ids they can access. |
| Full detail for one ad account — currency, time zone, language, account mode, financial status, and the parent customer id. |
| Accounts under one manager (customer) account. |
Tool | Purpose |
| List campaigns in an ad account, with budget, status, bid strategy, and campaign type. |
| List the ad groups in a campaign, with status, bids, and targeting settings. |
| List the ads in an ad group. |
| List the keywords in an ad group, with match type, bid, status, and final URLs. |
| List shared budgets in the account's budget library. |
| Create up to 100 campaigns in one call. |
| Update existing campaigns. |
| Permanently delete campaigns. |
| Pause or resume campaigns, ad groups, ads, or keywords by id. |
| Create up to 1000 ad groups in one campaign. |
| Update ad groups. |
| Permanently delete ad groups and everything under them. |
| Create up to 50 ads in one ad group. |
| Update ads. |
| Permanently delete ads from an ad group. |
| Add up to 1000 keywords to an ad group. |
| Update keywords — bids, status, final URLs. |
| Permanently delete keywords from an ad group. |
Tool | Purpose |
| Run a Microsoft Advertising performance report and return the rows. |
| Collect a report that run_report left in the 'pending' state, using its report_request_id. |
| Every report type run_report supports, with what it covers, how it can be scoped, and its default columns. |
Tool | Purpose |
| Read targeting criterions on a campaign or ad group — age, gender, device, location, ad schedule, audiences, or LinkedIn profile targeting. |
| Add targeting criterions to a campaign or ad group. |
| Update targeting criterions — most commonly to change a bid multiplier. |
| Remove targeting criterions. |
| Search LinkedIn company names and return their ProfileIds, for use with ProfileCriterion targeting. |
| Get a temporary download URL for Microsoft's targeting id reference files. |
Tool | Purpose |
| List audiences available to the account — remarketing lists, customer lists, in-market audiences, product audiences, and combined lists — with their sizes and membership durations. |
| Create audiences — remarketing lists, customer (customer-match) lists, product audiences, combined lists, or impression-based remarketing lists. |
| Update audiences. |
| Permanently delete audiences. |
| Add email addresses to a customer-match audience without removing existing members. |
| Permanently remove selected members from a customer-match audience. |
| Replace every member of a customer-match audience with the supplied addresses. |
Tool | Purpose |
| List ad extensions in the account's extension library — sitelinks, callouts, structured snippets, call, image, price, promotion, and review extensions. |
| Show which ad extensions are attached to which campaigns or ad groups. |
| Create ad extensions in the account library. |
| Update ad extensions. |
| Permanently delete ad extensions from the account library, removing them from every campaign and ad group they were associated with. |
| Attach ad extensions to campaigns or ad groups, which is what makes them serve. |
| Detach ad extensions from campaigns or ad groups WITHOUT deleting them. |
| List negative keywords set directly on campaigns or ad groups. |
| Add negative keywords to one campaign or ad group, stopping ads from showing on those searches. |
| Remove negative keywords from a campaign or ad group. |
| List labels in the account. |
| Create labels. |
| Attach labels to campaigns, ad groups, ads, or keywords. |
Tool | Purpose |
| List Universal Event Tracking tags on the account, including the tracking script for each. |
| Create UET tags. |
| List conversion goals with their type, attribution model, conversion window, revenue settings, and tracking status. |
| Create conversion goals. |
| Update conversion goals — rename them, change the conversion window, revenue value, or count type. |
| Upload conversions that happened away from the website — a phone sale, an in-store purchase, a CRM-qualified lead. |
| Restate or retract a conversion already uploaded — a refund, a cancelled order, or a corrected value. |
| Send conversion events server-side through the Microsoft Conversions API; the per-tag credential is fetched internally and never returned. |
Tool | Purpose |
| Microsoft Advertising's keyword planner: search volume, competition, and suggested bids for keyword ideas. |
| Estimate clicks, impressions, average CPC, and total cost for a set of keywords at a given bid — before spending anything on them. |
| Suggest keywords by reading the content of a web page. |
| Historical search volume for specific terms over time, independent of any campaign. |
| For existing keywords, show estimated clicks, impressions, and cost across a range of bids — the data behind 'what would happen if I bid more'. |
| Competitive auction data: who else shows up in the same auctions, their impression share, overlap rate, and position-above rate. |
Tool | Purpose |
| Export an account's entities in one operation and return them grouped by record type. |
| Collect a bulk export that bulk_download left pending, using its download_request_id. |
| Create, change, or delete many entities at once by uploading bulk records. |
| Collect a bulk upload that bulk_upload left pending, using its request_id. |
Tool | Purpose |
| Actual billed spend for an ad account in a given calendar month, in the account's currency. |
| Insertion orders on an account — the prepaid or invoiced spending agreements that cap and fund delivery, with their budget, balance, and start/end dates. |
| Invoice metadata for one or more accounts over a date range — document ids, amounts, and dates. |
Tool | Purpose |
| Set up a Google Ads import with new entities paused by default and deletion mirroring disabled. |
| Set up a Google Ads import that may delete Microsoft entities removed from Google. |
| List Google Ads import jobs configured for this account — their schedule, status, and when each last ran. |
| Results from completed Google Ads import runs: per-entity-type counts of additions, changes, deletions, and errors, plus an error log URL when a run had problems. |
| Delete Google Ads import jobs, stopping future scheduled runs. |
| Map Google Ads entity ids to the Microsoft Advertising ids they were imported as. |
Tool | Purpose |
| Call a read operation from the reviewed |
| Call an operation outside the raw-read allowlist through a conservatively destructive surface. |
| Show how this server reaches the Microsoft Advertising API: the resolved base URL for each service, which environment is active, and which services take account headers. |
Reads whose arguments project cleanly onto a URI are also registered as MCP
resources for clients that surface them. The resource families cover accounts,
the current user, account hierarchy and detail, campaigns, ad groups, ads,
keywords, budgets, audiences, UET tags, conversion goals, monthly spend, and
the report-type registry. Each family supports its documented path template
and, where arguments are available, a {query} variant. Structured reads such
as report requests and keyword searches remain tools only.
Five MCP prompts provide reviewed multi-tool workflows:
Prompt | Purpose |
| Audit structure, performance, delivery blockers, wasted spend, and quality. |
| Find non-converting search spend and draft negative-keyword recommendations. |
| Research and size keyword opportunities from required seed terms or a URL. |
| Compare billed spend, budgets, delivery, and insertion-order constraints. |
| Compare normalized Microsoft Advertising and Google Ads performance. |
Error 105 vs 106. 105 is authentication — usually production credentials against sandbox or vice versa. 106 is authorization — usually a mismatched account/customer pair, which this server resolves for you.
Use ConversionsQualified, not Conversions. The latter was deprecated in
2022 and always returns 0. Same for AveragePosition.
REST collection fields are operation-specific. Verified campaign and
conversion-goal flag fields use comma-delimited strings, while
GetKeywordIdeas.IdeaAttributes is a JSON array. Do not apply one global
flags-enum serialization rule to every REST field.
Batch writes half-succeed. Results carry a per-item outcome list with the
assigned id or the specific error. Check outcomes, not just succeeded.
Deletes, bulk upload, removal/replacement modes, conversion retractions, and
imports with deletion mirroring are marked destructive in their MCP annotations.
Created entities default to Paused. Pass Status: "Active" explicitly to
start delivery.
Reports may be incomplete. Clicks settle in ~2h and conversions in ~3h;
invalid-traffic adjustments can move historical numbers a week later. When
Microsoft flags a report, the response carries a data_warning.
Spend from billing ≠ spend from reports. Reports show delivery; billing
shows what was charged after credits. Use get_monthly_spend for finance
questions.
See .env.example for the full list. The essentials:
Variable | Purpose |
| Required in production |
| Entra app registration GUID |
| Strongly recommended (see above) |
| One is required |
| Default ad account |
|
|
bun install
bun run test # hermetic unit + protocol tests, no credentials needed
bun run typecheck
bun run lint
bun run dev # run the server on stdio
bun run inspect # MCP InspectorLive tests hit the real API and are opt-in:
MSADS_RUN_LIVE_TESTS=true MSADS_TEST_ACCOUNT_ID=... bun run test:live
bun run test:cleanup:dry # find orphaned test entitiesDesign decisions are in docs/SPEC.md; the API research behind them is in docs/RESEARCH.md.
MIT
This server cannot be deployed
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Microsoft Ads MCP server: 11 tools for search, PMax, Google Ads imports. Read-only by default.
Manage Google, Meta, Amazon, TikTok, LinkedIn & ChatGPT ads. 430 tools for campaigns & analytics.
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
