Microsoft Ads MCP Server (read + write)

An MCP server for Microsoft Advertising, using the Microsoft Advertising REST API v13 (the API formerly called the Bing Ads API). Use it from Claude, ChatGPT, Cursor, Codex or any MCP client to report on Search, Shopping and Performance Max campaigns, find keywords, and change campaigns, ad groups, ads, keywords, targeting, budgets and bids.

Maintained by AI Shopping Feeds. It offers:

• Coverage of the advertiser workflow: accounts, campaigns, ad groups, ads (with a responsive search ad helper), keywords and negatives, Performance Max asset groups, targeting and audiences, shared budgets, portfolio bid strategies, labels, reports, change history, keyword ideas, estimates, recommendations and bulk download

• Safety: dry-run, confirm words for deletes, big batches and spend rises, new campaigns created paused, an audit log with before-snapshots, read-only mode and tool groups

• An escape hatch for every other REST v13 operation, read-only or confirm-gated

Microsoft also runs a hosted Microsoft Advertising MCP Server that you connect with your own Entra app. Its documented scenarios are reporting, analysis, assets and change history. This one runs on your own machine and adds guarded write tools. More in docs/terms-and-data.md.

Not affiliated with or endorsed by Microsoft.

Part of the AI Shopping Feeds MCP family: Google Ads · Google Merchant Centre · Google Analytics · YouTube Studio · Amazon Ads · Apple Ads · Microsoft Ads · TikTok Ads · Pinterest Ads · Snapchat Ads · OpenAI Ads · AppLovin.

Let your agent set it up

Paste this into Claude Code, Codex, Cursor or any agent that can read web pages and edit files:

Set up the Microsoft Ads MCP server for me by following https://raw.githubusercontent.com/AI-Shopping-Feeds/microsoft-ads-mcp/main/skills/microsoft-ads-mcp/SKILL.md

The agent checks whether it's already connected, installs the runner if you agree, walks you through the developer token, the Entra app registration and sign-in, adds the server to your client's config without touching your other servers, and checks it works by calling microsoft_ads_health_check.

The same file is an Agent Skill, so your agent can keep it as a guide to using the tools well. For Claude Code, copy the folder into your skills:

git clone --depth 1 https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git /tmp/microsoft-ads-mcp
cp -r /tmp/microsoft-ads-mcp/skills/microsoft-ads-mcp ~/.claude/skills/

Other agents that support skills load the same skills/microsoft-ads-mcp folder from their own skills directory.

Related MCP server: microsoft-ads-mcp

What it can do

70 tools, all prefixed microsoft_ads_. The full list is in docs/tools.md.

Read

Write

Safety

• Dry-run (MICROSOFT_ADS_DRY_RUN=true or microsoft_ads_set_dry_run) records writes and returns a preview without sending them.

• Confirm words: deletes need confirm="DELETE". Batches over 10 items, bid or budget rises over 20% (or where the current value can't be read), values over your caps, enabling campaigns, applying recommendations and raw writes need confirm="APPLY". A refused call shows what it would send.

• New campaigns, ad groups and asset groups are created paused unless you set Status.

• Audit log of every write and rehearsal, with a before-snapshot, in ~/.microsoft-ads-mcp/logs/audit.jsonl (owner-only). Entries older than 30 days are pruned; microsoft-ads-mcp purge deletes the log and the stored token. Report rows stay in memory and downloads are capped at 200 MB.

• Read-only mode (MICROSOFT_ADS_READ_ONLY=true) and tool groups (MICROSOFT_ADS_TOOL_GROUPS) limit what the agent can see.

• Spend guards: MICROSOFT_ADS_MAX_INCREASE_PCT, MICROSOFT_ADS_MAX_DAILY_BUDGET and MICROSOFT_ADS_MAX_BID.

• The HTTP transports refuse to bind to a non-loopback address unless you set MICROSOFT_ADS_ALLOW_REMOTE=true.

• Only Microsoft Advertising and Microsoft sign-in hosts are called. Terms, data handling and limits: docs/terms-and-data.md.

Supported clients

Setup

1. Install uv

The server runs with uvx from uv (brew install uv on macOS) and needs Python 3.11 or later. It installs straight from this repository:

uvx --from git+https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git microsoft-ads-mcp

Pin a release by adding @vX.Y.Z to the URL.

2. Get credentials

1. Developer token: a Super Admin of your Microsoft Advertising account requests one in Microsoft Advertising under Settings > Developer settings. Microsoft says it is issued straight away for your own accounts and can take up to five business days if you manage other people's accounts. Not needed for the sandbox.

2. App registration: in the Azure portal (Microsoft Entra ID > App registrations), register an app for any organisational directory and personal Microsoft accounts, and add the redirect URI http://localhost:8765/callback under Mobile and desktop applications. Copy the Application (client) ID.

3. Sign in once with the Microsoft account that manages the ads:

   MICROSOFT_ADS_CLIENT_ID=your-client-id MICROSOFT_ADS_DEVELOPER_TOKEN=your-developer-token \
     uvx --from git+https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git microsoft-ads-mcp auth

   It saves a refresh token to ~/.microsoft-ads-mcp/secrets/microsoft-ads-token.json (owner-only). Add --manual if the browser can't reach localhost.

Step by step, with the sandbox, agencies and troubleshooting: docs/setup-microsoft-ads-api.md.

3. Add it to your client

Replace the placeholders. Keep your other servers in each file. The token file from step 2 is found automatically.

Claude Code

claude mcp add --scope user microsoft-ads \
  --env MICROSOFT_ADS_CLIENT_ID=your-client-id \
  --env MICROSOFT_ADS_DEVELOPER_TOKEN=your-developer-token \
  --env MICROSOFT_ADS_ACCOUNT_ID=123456789 \
  -- uvx --from git+https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git microsoft-ads-mcp

Claude Desktop, Cursor, Gemini CLI, Windsurf (and VS Code under servers)

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git", "microsoft-ads-mcp"],
      "env": {
        "MICROSOFT_ADS_CLIENT_ID": "your-client-id",
        "MICROSOFT_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "MICROSOFT_ADS_ACCOUNT_ID": "123456789"
      }
    }
  }
}

Desktop apps often can't find uvx on the PATH; if the server doesn't start, use the full path from which uvx as the command. If you keep the token somewhere else, add "MICROSOFT_ADS_TOKEN_FILE": "/abs/path/microsoft-ads-token.json".

Codex (~/.codex/config.toml)

[mcp_servers.microsoft-ads]
command = "uvx"
args = ["--from", "git+https://github.com/AI-Shopping-Feeds/microsoft-ads-mcp.git", "microsoft-ads-mcp"]
env = { MICROSOFT_ADS_CLIENT_ID = "your-client-id", MICROSOFT_ADS_DEVELOPER_TOKEN = "your-developer-token", MICROSOFT_ADS_ACCOUNT_ID = "123456789" }

You can also put these settings in ~/.microsoft-ads-mcp/.env instead of the client config.

4. Check it works

Restart or reload the client, then ask it "which Microsoft Advertising accounts can you see?". It should call microsoft_ads_health_check and list your accounts. Set MICROSOFT_ADS_ACCOUNT_ID to the one you use most; tools also take an account_id.

Configuration

Settings are read from the environment, --env FILE, ./.env and then ~/.microsoft-ads-mcp/.env. CLI: microsoft-ads-mcp run (default), auth, purge, describe, version.

Example prompts

Which campaigns spent the most last week, and what was their cost per conversion?

Lower keyword bids by 10% in the "Running shoes" ad group for keywords with no conversions in 30 days. Dry-run first and show me the table.

Add "free" and "cheap" as phrase negatives to all my Search campaigns.

What changed in the account in the last seven days, and who changed it?

More docs

• All tools and confirm words

• Getting Microsoft Advertising API access, step by step

• Terms, data handling and Microsoft's own MCP server

• Agent skill: setup and usage guide for agents

• Changelog and security policy

Contributing and licence

Issues and pull requests are welcome on this repository. See CONTRIBUTING.md.

Licensed under the MIT License.

Try out AI Shopping Feeds, our shopping feed management tool (including Google Shopping feeds).