Skip to main content
Glama
microsoft-ads-mcp

microsoft-ads-mcp

by james-julius

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

list_accounts

Accounts the signed-in user can access

list_campaigns

Campaigns in an account

list_ad_groups

Ad groups in a campaign

list_keywords

Keywords in an ad group

list_ads

Ads in an ad group

list_negative_keywords

Campaign-level negatives

performance_report

account / campaign / ad_group / ad / keyword / search_term / geographic reports, predefined or custom date ranges, any aggregation

find_wasted_spend

Search terms that spent with no conversions (negative-keyword candidates)

Write / management

Tool

Description

set_campaign_status

Pause / enable a campaign

set_campaign_budget

Set daily budget

set_ad_group_status

Pause / enable an ad group

set_keyword

Update keyword status / bid

add_negative_keywords / remove_negative_keywords

Manage negatives

create_campaign

New Search campaign (paused)

create_ad_group

New ad group (paused)

add_keywords

Add keywords

add_responsive_search_ad

Add a Responsive Search Ad

Higher-level (composite)

Tool

Description

account_overview

One call: account KPIs + per-campaign breakdown + flags (zero-conversion spenders, budget-limited campaigns)

compare_periods

Last N days vs the preceding N days, with deltas and % change

optimization_audit

Prioritized action list: waste, low quality score, high CPA, scale candidates, budget-limited campaigns

search_term_harvest

Converting search queries not yet keywords — suggestions to add

apply_negatives_from_waste

Turn wasted search terms into negative keywords (dry-run by default)

build_search_campaign

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

  1. A Microsoft Advertising account you can sign into.

  2. 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.

  3. Python 3.10–3.13 (the bingads SOAP 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 .env

Configure 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.

  1. In the Google Cloud Console: pick/create a project.

  2. 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).

  3. Credentials → Create credentials → OAuth client ID → Application type Web application → Authorized redirect URI http://localhost:8400 → Create.

  4. 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)

  1. 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.

  2. API permissions → Add → APIs my organization uses → "Microsoft Advertising API" (or the ads.microsoft.com/msads.manage scope).

  3. 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-auth

This 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-mcp

Claude 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

MSADS_AUTH_PROVIDER

google

google or microsoft

MSADS_DEVELOPER_TOKEN

—

required

MSADS_GOOGLE_CLIENT_ID / _SECRET

—

required for Google

MSADS_CLIENT_ID

—

required for Microsoft

MSADS_TENANT

common

Microsoft only

MSADS_CLIENT_SECRET / MSADS_REDIRECT_URI

—

Microsoft confidential app

MSADS_LOOPBACK_PORT

8400

must match the registered redirect

MSADS_ENVIRONMENT

production

production or sandbox

MSADS_TOKEN_FILE

~/.config/microsoft-ads-mcp/tokens.json

refresh-token store

License

MIT — see LICENSE.

Available Tools

26 tools
account_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_negatives_to_shared_listA

Add negative keywords to a shared list (applies to every campaign the list is attached to). Prefer this over per-campaign negatives when an account uses a shared negatives list. match_type = "Exact" or "Phrase".

Inputs: texts (required), list_id (required), account_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

list_shared_negative_listsA

List account-level negative-keyword lists (shared across campaigns): id, name, how many campaigns it's attached to, and item count.

Inputs: account_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

    A3.7/5.0

    Scored across 26 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      This 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/mcp
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Production-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.
      9
      148 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      66
      MIT