Microsoft Ads 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

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

Tool	Description
get_auth_url()	Get OAuth URL for sign-in
complete_auth(redirect_url)	Complete OAuth with redirect URL

Accounts

Tool	Description
search_accounts()	List all accessible advertising accounts

Campaigns

Tool	Description
get_campaigns(include_deleted?)	List all campaigns
create_campaign(name, daily_budget, description?)	Create a search campaign (paused by default)
update_campaign_status(campaign_id, status)	Set campaign to Active or Paused

Ad Groups

Tool	Description
get_ad_groups(campaign_id)	List ad groups in a campaign
create_ad_group(campaign_id, name, cpc_bid?)	Create an ad group

Keywords

Tool	Description
get_keywords(ad_group_id)	List keywords in an ad group
add_keywords(ad_group_id, keywords, match_type?, default_bid?)	Add keywords (comma-separated)

Ads

Tool	Description
get_ads(ad_group_id)	List ads in an ad group
create_responsive_search_ad(ad_group_id, final_url, headlines, descriptions, path1?, path2?)	Create an RSA

Reporting

Tool	Description
submit_campaign_performance_report(date_range?, columns?)	Submit campaign report request
submit_keyword_performance_report(date_range?, columns?)	Submit keyword report request
submit_search_query_report(date_range?, columns?)	Submit search terms report request
submit_geographic_report(date_range?, columns?)	Submit geo report request
poll_report_status(report_id?)	Check report status and get download URL

Other

Tool	Description
get_budgets()	View campaign budgets
get_labels(label_ids?)	Get label information

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