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

Write / management

Higher-level (composite)

Report numbers come back already typed (floats/ints; percentages as plain numbers, e.g. 1.89 means 1.89%).

Related MCP server: mcp-server-bing-webmaster

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

License

MIT — see LICENSE.