microsoft-ads-mcp
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., "@microsoft-ads-mcp show me the performance report for my campaigns last month"
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-ads-mcp
An MCP server for the Microsoft Advertising (Bing Ads) API. Gives an MCP client (Claude Code, Claude Desktop, etc.) live read and management access to your Microsoft Advertising accounts — reporting, campaign structure, and full write operations.
Works with Microsoft Advertising accounts that sign in with Google (the default) or with a Microsoft account.
⚠️ This server can change live campaigns and spend real money (enabling campaigns, raising budgets). Tools that affect spend are clearly marked and the server is designed to keep newly-created entities paused by default — but treat it like giving an assistant the keys to your ad account.
Tools
Read / analytics
Tool | Description |
| Accounts the signed-in user can access |
| Campaigns in an account |
| Ad groups in a campaign |
| Keywords in an ad group |
| Ads in an ad group |
| Campaign-level negatives |
| account / campaign / ad_group / ad / keyword / search_term / geographic reports, predefined or custom date ranges, any aggregation |
| Search terms that spent with no conversions (negative-keyword candidates) |
Write / management
Tool | Description |
| Pause / enable a campaign |
| Set daily budget |
| Pause / enable an ad group |
| Update keyword status / bid |
| Manage negatives |
| New Search campaign (paused) |
| New ad group (paused) |
| Add keywords |
| Add a Responsive Search Ad |
Higher-level (composite)
Tool | Description |
| One call: account KPIs + per-campaign breakdown + flags (zero-conversion spenders, budget-limited campaigns) |
| Last N days vs the preceding N days, with deltas and % change |
| Prioritized action list: waste, low quality score, high CPA, scale candidates, budget-limited campaigns |
| Converting search queries not yet keywords — suggestions to add |
| Turn wasted search terms into negative keywords (dry-run by default) |
| Create a whole campaign (campaign + ad group + keywords + RSA) in one call, paused |
Report numbers come back already typed (floats/ints; percentages as plain
numbers, e.g. 1.89 means 1.89%).
Related MCP server: Bing Ads MCP Server
How auth works
Microsoft Advertising has no app-only flow — every call needs a delegated
user token. You authorize once; the refresh token is stored at
~/.config/microsoft-ads-mcp/tokens.json (mode 0600) and the server silently
exchanges it for access tokens thereafter. You also need a Microsoft Advertising
developer token.
Choose a provider with MSADS_AUTH_PROVIDER:
google(default) — for Ads accounts created via "Sign in with Google".microsoft— for Ads accounts backed by an Entra or personal Microsoft account.
Prerequisites
A Microsoft Advertising account you can sign into.
A developer token: sign in at https://developers.ads.microsoft.com/, and request a token (production tokens for accounts you own are granted immediately). This is separate from OAuth.
Python 3.10–3.13 (the
bingadsSOAP stack isn't happy on 3.14 yet).
Install
git clone https://github.com/james-julius/microsoft-ads-mcp.git
cd microsoft-ads-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env # then edit .envConfigure auth
Option A — Google (default)
The Microsoft Advertising API accepts Google sign-in (SDK ≥ 13.0.26), so you can authenticate with the same Google account you use at ads.microsoft.com.
In the Google Cloud Console: pick/create a project.
APIs & Services → OAuth consent screen → Internal (Workspace org) or External + add your email as a Test user. Scopes are just
openid email profile(nothing sensitive — no Google verification needed).Credentials → Create credentials → OAuth client ID → Application type Web application → Authorized redirect URI
http://localhost:8400→ Create.Put the values in
.env:MSADS_AUTH_PROVIDER=google MSADS_DEVELOPER_TOKEN=your-developer-token MSADS_GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com MSADS_GOOGLE_CLIENT_SECRET=GOCSPX-xxxx
Option B — Microsoft (Entra)
Entra portal → App registrations → New registration.
Supported account types: Accounts in any org directory and personal Microsoft accounts.
Authentication → Add a platform → Mobile and desktop applications → redirect
http://localhost:8400; set Allow public client flows = Yes.
API permissions → Add → APIs my organization uses → "Microsoft Advertising API" (or the
ads.microsoft.com/msads.managescope).Put the values in
.env:MSADS_AUTH_PROVIDER=microsoft MSADS_DEVELOPER_TOKEN=your-developer-token MSADS_CLIENT_ID=your-application-client-id MSADS_TENANT=common # For a confidential (Web) app instead of public client, also set: # MSADS_CLIENT_SECRET=... # MSADS_REDIRECT_URI=http://localhost:8400
Authorize (one time)
.venv/bin/microsoft-ads-authThis opens your browser on a loopback redirect, captures the auth code locally (nothing to copy/paste), and saves the refresh token.
Register with your MCP client
Claude Code
claude mcp add microsoft-ads -s user -- /absolute/path/to/microsoft-ads-mcp/.venv/bin/microsoft-ads-mcpClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"microsoft-ads": {
"command": "/absolute/path/to/microsoft-ads-mcp/.venv/bin/microsoft-ads-mcp"
}
}
}Restart Claude Desktop.
The server finds its .env from the project root, so no env vars are needed in
the client config.
Example prompts
"List my Microsoft Ads campaigns and their last-30-day spend and conversions."
"Find wasted spend in the last 30 days and suggest negative keywords."
"Add 'free' and 'jobs' as phrase negatives to campaign X."
"Create a paused Search campaign 'Brand' with a $10 daily budget."
Configuration reference
Env var | Default | Notes |
|
|
|
| — | required |
| — | required for Google |
| — | required for Microsoft |
|
| Microsoft only |
| — | Microsoft confidential app |
|
| must match the registered redirect |
|
|
|
|
| refresh-token store |
License
MIT — see LICENSE.
Available Tools
26 toolsaccount_overviewA
One-call health snapshot: account KPIs + per-campaign breakdown + flags (zero-conversion spenders, campaigns losing impressions to budget). Best starting point for "how are my ads doing?".
Inputs: account_id (required), predefined_time. Returns: object
add_keywordsA
Add keywords to an ad group. Each item: {text, match_type (Broad|Phrase|Exact), bid (optional float), status (optional, default Active)}. Returns new keyword ids.
Inputs: keywords (required), account_id (required), ad_group_id (required). Returns: object
add_negative_keywordsA
Add campaign-level negative keywords to stop ads showing for those terms. match_type = "Exact" or "Phrase". Returns the new negative keyword ids.
Inputs: texts (required), account_id (required), campaign_id (required), match_type. Returns: object
add_responsive_search_adA
Add a Responsive Search Ad. Needs 3-15 headlines (<=30 chars each) and 2-4 descriptions (<=90 chars each). path1/path2 are optional display-url paths. Returns the new ad id.
Inputs: final_url (required), headlines (required), account_id (required), ad_group_id (required), +3 more. Returns: object
apply_negatives_from_wasteA
Find wasted search terms (spend with no conversions) and add them as campaign negative keywords. dry_run=True (default) returns the plan only; set dry_run=False to actually apply. Confirm with the user before applying.
Inputs: account_id (required), limit, dry_run, lookback, +2 more. Returns: object
build_search_campaignA
Create a full Search campaign in one call: campaign + ad group + keywords +
a Responsive Search Ad. Everything is created PAUSED. keywords may be plain
strings or {text, match_type, bid} objects. Needs 3-15 headlines and 2-4
descriptions for the ad.
Inputs: name (required), keywords (required), final_url (required), headlines (required), +6 more. Returns: object
compare_periodsA
Compare the last days days vs the immediately preceding days days.
Returns each metric's current, prior, delta, and % change. report_type:
account (default) or campaign/keyword/etc. for the totals scope.
Inputs: account_id (required), days, report_type. Returns: object
create_ad_groupA
Create an ad group in a campaign (English, given default CPC bid). Defaults to PAUSED. Returns the new ad_group_id.
Inputs: name (required), account_id (required), campaign_id (required), status, +1 more. Returns: object
create_campaignA
Create a Search campaign (Manual CPC). Defaults to PAUSED so it never spends until you explicitly enable it. Returns the new campaign_id.
Inputs: name (required), account_id (required), daily_budget (required), status. Returns: object
find_wasted_spendA
Find search terms that burned money with little/no return — spend >= min_spend and conversions <= max_conversions — sorted by spend descending. These are prime candidates to add as negative keywords.
Inputs: account_id (required), max_rows, min_spend, max_conversions, +1 more. Returns: result
list_accountsA
List all Microsoft Advertising accounts the signed-in user can access (id, name, number, customer id). Start here to get an account_id.
Inputs: no named parameters. Returns: result
list_ad_groupsA
List ad groups in a campaign: id, name, status, cpc bid.
Inputs: account_id (required), campaign_id (required). Returns: result
list_adsA
List ads in an ad group: id, type, status, final urls.
Inputs: account_id (required), ad_group_id (required). Returns: result
list_campaignsA
List campaigns in an account: id, name, status, type, daily budget.
Inputs: account_id (required). Returns: result
list_keywordsA
List keywords in an ad group: id, text, match type, status, bid.
Inputs: account_id (required), ad_group_id (required). Returns: result
list_negative_keywordsA
List campaign-level negative keywords (id, text, match type).
Inputs: account_id (required), campaign_id (required). Returns: result
optimization_auditA
Audit the account and return a prioritized action list plus the supporting detail: wasted search terms, wasted keywords, low-quality-score keywords, keywords above target CPA (if target_cpa given), top keywords to scale, and campaigns limited by budget. Read-only — suggests, doesn't change anything.
Inputs: account_id (required), lookback, target_cpa, min_wasted_spend. Returns: object
performance_reportA
Pull a performance report. Numbers come back already typed (floats/ints; percentages as plain numbers, e.g. 1.89 means 1.89%).
Args: account_id: Ads account id. report_type: account | campaign | ad_group | ad | keyword | search_term | geographic. - search_term = actual user search queries (best for finding waste + new keywords) - keyword / ad_group / ad = entity performance incl. quality score - geographic = performance by country/state/city predefined_time: Today, Yesterday, LastSevenDays, Last14Days, Last30Days, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. Ignored if start_date+end_date given. start_date / end_date: custom range YYYY-MM-DD (both required for custom). aggregation: Summary, Daily, Weekly, Monthly, Hourly (TimePeriod column is auto-dropped for Summary). campaign_ids: optional scope to specific campaigns. columns: optional explicit column list (defaults are sensible per report).
Inputs: account_id (required), columns, end_date, max_rows, +5 more. Returns: result
remove_negative_keywordsA
Remove campaign-level negative keywords by id (from list_negative_keywords).
Inputs: account_id (required), campaign_id (required), negative_keyword_ids (required). Returns: object
search_term_harvestC
Converting search queries that aren't already exact keywords — suggestions to add as keywords (with the ad group they triggered in). The growth mirror of find_wasted_spend.
Inputs: account_id (required), limit, lookback, min_conversions. Returns: result
set_ad_group_statusA
Pause or enable an ad group. status = "Active" or "Paused".
Inputs: status (required), account_id (required), ad_group_id (required), campaign_id (required). Returns: object
set_campaign_budgetA
Set a campaign's daily budget (account currency). WARNING: raising budget raises potential spend. Confirm increases with the user.
Inputs: account_id (required), campaign_id (required), daily_budget (required). Returns: object
set_campaign_statusA
Pause or enable a campaign. status = "Active" or "Paused". WARNING: "Active" lets the campaign spend. Confirm with the user first.
Inputs: status (required), account_id (required), campaign_id (required). Returns: object
set_keywordA
Update a keyword's status ("Active"/"Paused") and/or bid (account currency). Provide at least one of status or bid.
Inputs: account_id (required), keyword_id (required), ad_group_id (required), bid, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Tools are mostly distinct with clear resource/action pairing (list_campaigns vs list_ad_groups vs set_campaign_status). A few analytics tools (account_overview, performance_report, compare_periods) have overlapping report-like purposes but their descriptions clarify different use cases.
The majority use verb_noun (list_*, set_*, add_*, create_*), but several key tools break the pattern with noun-first names (performance_report, account_overview, optimization_audit, search_term_harvest). This mixed convention is readable but not fully predictable.
26 tools exceeds the typical 3-15 sweet spot, but the breadth of Microsoft Ads management (accounts, campaigns, ad groups, keywords, ads, negatives, shared lists, reporting, optimization) justifies the count. Each tool serves a distinct purpose; none are redundant.
Core lifecycle coverage is solid: create/list/set-update for campaigns, ad groups, keywords, and ads, plus negative keyword management and rich reporting. Minor gaps include no way to delete keywords/ads, no ad group bid update after creation, and shared list management limited to adding negatives (no remove/create/delete list tools).
Maintenance
Related MCP Connectors
Microsoft Ads (Bing Ads) MCP server: read reports and draft campaign changes from AI.
Microsoft Ads MCP server: 11 tools for search, PMax, Google Ads imports. Read-only by default.
Google Ads MCP server — manage campaigns, keywords, and metrics.
LinkedIn Ads MCP server: run LinkedIn campaigns, ad groups, ads and reports from AI.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceThis read-only MCP Server allows you to connect to Bing Ads data from Claude Desktop through CData JDBC Drivers. Free (beta) read/write servers available at https://www.cdata.com/solutions/mcp3MIT
- AlicenseAqualityBmaintenanceProduction-grade MCP server for Microsoft Advertising (Bing Ads) API. Enables Claude to manage Bing/Microsoft Ads accounts with full campaign, ad group, keyword, and performance analysis capabilities.9148 npm4MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for Microsoft Advertising (Bing Ads / DuckDuckGo Ads). This server enables AI assistants to create, manage, and report on Microsoft Advertising campaigns programmatically.2MIT
- AlicenseAqualityCmaintenanceMCP server for Microsoft Advertising (Bing Ads) REST API enabling agent-led campaign management and reporting. It provides tools to manage campaigns, ad groups, keywords, ads, budgets, and pull performance reports.66MIT