Microsoft Ads MCP Server

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.

Features

Authentication

• OAuth 2.0 authentication flow with token persistence

• Automatic token refresh

Campaign Management

• Campaigns: Create, list, pause/activate search campaigns

• Ad Groups: Create and list ad groups within campaigns

• Keywords: Add keywords with Broad, Phrase, or Exact match types

• Ads: Create Responsive Search Ads (RSAs) with multiple headlines and descriptions

Reporting

• Campaign performance reports

• Keyword performance reports

• Search query reports (actual search terms)

• Geographic performance reports

• Async report generation with polling

Account Management

• List all accessible accounts

• View campaign budgets

• Label management

Related MCP server: Bing Ads MCP Server

Prerequisites

1. Microsoft Advertising Account: Sign up at ads.microsoft.com

2. Developer Token: Apply at Microsoft Advertising Developer Portal

3. Azure AD App Registration: Create an app in Azure Portal with:

   • Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient

   • API permissions: Microsoft Advertising API

Installation

# Clone the repository
git clone https://github.com/Duartemartins/microsoft-ads-mcp-server.git
cd microsoft-ads-mcp-server

# Install dependencies
pip install -r requirements.txt

Configuration

Environment Variables

Create a .env file or set these environment variables:

MICROSOFT_ADS_DEVELOPER_TOKEN=your_developer_token
MICROSOFT_ADS_CLIENT_ID=your_azure_app_client_id
MICROSOFT_ADS_CUSTOMER_ID=your_customer_id      # Optional, discovered during auth
MICROSOFT_ADS_ACCOUNT_ID=your_account_id        # Optional, discovered during auth

Token Storage

Tokens are stored in ~/.config/microsoft-ads/tokens.json after authentication.

Usage

With Claude Code / mcporter

Add to your ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "python3",
      "args": ["/path/to/microsoft-ads-mcp-server/server.py"],
      "type": "stdio",
      "env": {
        "MICROSOFT_ADS_DEVELOPER_TOKEN": "your_token",
        "MICROSOFT_ADS_CLIENT_ID": "your_client_id"
      }
    }
  }
}

Standalone

python server.py

Authentication Flow

1. Call get_auth_url() to get the OAuth URL

2. Open the URL in a browser and sign in with your Microsoft account

3. After authorization, copy the redirect URL (starts with https://login.microsoftonline.com/common/oauth2/nativeclient?code=...)

4. Call complete_auth(redirect_url) with the full redirect URL

5. Your tokens are now saved and will auto-refresh

Available Tools

Authentication

Accounts

Campaigns

Ad Groups

Keywords

Ads

Reporting

Other

Example Workflow

# 1. Authenticate (first time only)
get_auth_url()
# Open URL in browser, sign in, copy redirect URL
complete_auth("https://login.microsoftonline.com/common/oauth2/nativeclient?code=...")

# 2. Check your account
search_accounts()

# 3. Create a campaign
create_campaign(name="My Search Campaign", daily_budget=20)

# 4. Create an ad group
create_ad_group(campaign_id=123456, name="Product Keywords", cpc_bid=1.50)

# 5. Add keywords
add_keywords(
    ad_group_id=789012,
    keywords="buy widgets, widget store, best widgets",
    match_type="Phrase",
    default_bid=1.25
)

# 6. Create an ad
create_responsive_search_ad(
    ad_group_id=789012,
    final_url="https://example.com/widgets",
    headlines="Buy Widgets Online|Best Widget Store|Free Shipping on Widgets",
    descriptions="Shop our huge selection of widgets. Free shipping on orders over $50.|Quality widgets at great prices. Order today!"
)

# 7. Activate the campaign
update_campaign_status(campaign_id=123456, status="Active")

# 8. Check performance later
submit_campaign_performance_report(date_range="LastWeek")
poll_report_status()

Why Microsoft Advertising?

• DuckDuckGo Integration: Microsoft Advertising powers DuckDuckGo search ads, reaching privacy-conscious users

• Lower CPCs: Often 30-50% cheaper than Google Ads for similar keywords

• Bing + Yahoo + AOL: Access to the Microsoft Search Network

• Import from Google: Easy migration of existing Google Ads campaigns

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with FastMCP

• Uses the Bing Ads Python SDK