MCP 服务器

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.

README

Microsoft Ads MCP Server

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

Microsoft Advertising Account: Sign up at ads.microsoft.com
Developer Token: Apply at Microsoft Advertising Developer Portal
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

Call get_auth_url() to get the OAuth URL
Open the URL in a browser and sign in with your Microsoft account
After authorization, copy the redirect URL (starts with https://login.microsoftonline.com/common/oauth2/nativeclient?code=...)
Call complete_auth(redirect_url) with the full redirect URL
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)

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