npm.io
1.3.3 • Published 1 week agoCLI

mcp-bing-ads

Licence
MIT
Version
1.3.3
Deps
6
Size
104 kB
Vulns
3
Weekly
0
Stars
4

Bing Ads MCP Server

npm version npm downloads GitHub stars License: MIT

Production-grade MCP server for Microsoft Advertising (Bing Ads) API. Enables Claude to manage Bing/Microsoft Ads accounts with full campaign, ad group, keyword, and performance analysis capabilities.

Features:

  • 13 tools (9 read, 4 write) -- production-tested
  • Campaign, ad group, and keyword management
  • Keyword performance analysis with quality scores
  • Search term reporting & bid automation
  • Budget & bid strategy optimization
  • Campaign-level budget updates
  • Negative keyword management (shared + campaign-level)

Note: Microsoft also publishes an official, read-only Microsoft Advertising MCP server (open pilot). This server adds search term and Quality Score reporting, shared negative list audits, and a small set of guarded write tools.

Installation

npm install mcp-bing-ads

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

  1. Get OAuth credentials:

    • Go to Microsoft Azure Portal
    • Create an Azure AD app registration
    • Grant API permissions: Microsoft Advertising API
    • Scopes: https://ads.microsoft.com/msads.manage offline_access
  2. Create config.json:

    cp config.example.json config.json
  3. Fill in your credentials:

    {
      "oauth": {
        "client_id": "YOUR_AZURE_CLIENT_ID",
        "client_secret": "YOUR_AZURE_CLIENT_SECRET"
      },
      "clients": {
        "default": {
          "customer_id": "YOUR_CUSTOMER_ID",
          "account_id": "YOUR_ACCOUNT_ID",
          "name": "My Account"
        }
      }
    }
  4. Set environment variables (recommended):

    export BING_ADS_DEVELOPER_TOKEN="your_developer_token"
    export BING_ADS_CLIENT_ID="your_client_id"
    export BING_ADS_REFRESH_TOKEN="your_refresh_token"
    # Optional:
    export BING_ADS_CLIENT_SECRET="your_client_secret"
    # Optional: opt into mutating tools (read-only by default)
    export BING_ADS_MCP_WRITE="true"
Environment Variables
Variable Required Default Description
BING_ADS_DEVELOPER_TOKEN yes -- Microsoft Advertising developer token
BING_ADS_CLIENT_ID yes -- Azure AD app client ID
BING_ADS_REFRESH_TOKEN yes -- OAuth refresh token
BING_ADS_CLIENT_SECRET no -- Azure AD app client secret (if confidential client)
BING_ADS_MCP_WRITE no false Set to true, 1, or yes to expose mutating tools (pause/update/add). Any other value -- or unset -- keeps the server read-only.
Read-only by default

Mutating tools (bing_ads_pause_keywords, bing_ads_update_campaign_budget, bing_ads_update_ad_group_cpc_bid, bing_ads_add_shared_negatives) are hidden from the tool list and refused at call time unless BING_ADS_MCP_WRITE=true is set in the server environment. This is a safety gate against casual write actions -- for example, pausing a keyword or editing a budget based on a throwaway chat message. To make write changes, set the env var explicitly in your .mcp.json or shell profile for the session that needs it, then unset it afterwards. Read tools (list/report/performance) are always available.

Usage

Use with Claude Code

The server runs locally over stdio; your MCP client starts it. Add to ~/.claude.json (or a project .mcp.json):

{
  "mcpServers": {
    "bing-ads": {
      "command": "npx",
      "args": ["-y", "mcp-bing-ads"],
      "env": {
        "BING_ADS_DEVELOPER_TOKEN": "your_developer_token",
        "BING_ADS_CLIENT_ID": "your_client_id",
        "BING_ADS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Example API Calls
// Get client context
bing_ads_get_client_context({ working_directory: "/path/to/project" })

// List campaigns
bing_ads_list_campaigns()

// Get campaign performance
bing_ads_get_campaign_performance({
  start_date: "2026-01-01",
  end_date: "2026-03-01"
})

// Get keyword performance
bing_ads_keyword_performance({
  start_date: "2026-02-01",
  end_date: "2026-03-01"
})

// Create negative keywords
bing_ads_add_shared_negatives({
  shared_list_id: "list_123",
  keywords: [
    { text: "cheap", match_type: "Phrase" },
    { text: "discount", match_type: "Exact" }
  ]
})

API Reference

Context
  • bing_ads_get_client_context(working_directory) -- Detect account from working directory
Campaigns
  • bing_ads_list_campaigns() -- List all campaigns
  • bing_ads_get_campaign_performance(start_date, end_date) -- Campaign metrics
  • bing_ads_update_campaign_budget(campaign_id, daily_budget) -- Update daily spend
Ad Groups
  • bing_ads_list_ad_groups(campaign_id) -- List ad groups in campaign
Keywords
  • bing_ads_keyword_performance(start_date, end_date, [campaign_ids]) -- Keyword metrics & QS
  • bing_ads_search_term_report(start_date, end_date) -- Search terms that triggered ads
  • bing_ads_pause_keywords(ad_group_id, keyword_ids) -- Pause keywords
Negative Keywords
  • bing_ads_list_shared_entities([type]) -- List shared negative lists
  • bing_ads_add_shared_negatives(list_id, keywords) -- Add to shared list
Performance Reports
  • Campaign performance (ROI, conversions, CTR, CPC)
  • Keyword performance (QS, expected CTR, ad relevance, landing page experience)
  • Search term insights (which queries are converting)

Key Metrics & Definitions

Quality Score (QS): 1-10 rating of keyword quality

  • 1-3: Poor
  • 4-6: Average
  • 7-10: Excellent

Expected CTR: 1-9 rating of expected click-through rate Ad Relevance: 1-9 rating of relevance to search query Landing Page Experience: 1-9 rating of landing page quality

CLI Tools

npm run dev                 # Run in dev mode (tsx)
npm run build             # Compile TypeScript
npm test                  # Run contract tests

Architecture

Files:

  • src/index.ts — MCP server, OAuth flow, tool handlers
  • src/tools.ts — Tool schema definitions
  • src/errors.ts — Error handling & classification
  • config.json — Credentials & client mapping

Error Classification:

  • Authentication errors (token expired)
  • Rate limit errors (retry with backoff)
  • Service errors (API temporarily unavailable)
  • Validation errors (bad input)

Development

Adding a New Tool
  1. Define schema in src/tools.ts
  2. Add handler in src/index.ts tool dispatch
  3. Add contract test in .contract.test.ts
  4. Test with npm test
Testing
npm test -- --run        # Single run
npm test -- --watch      # Watch mode

Troubleshooting

Config file not found
cp config.example.json config.json
# Fill in your Azure credentials and Bing Ads IDs
Missing required credentials

Check that:

  • BING_ADS_DEVELOPER_TOKEN, BING_ADS_CLIENT_ID, and BING_ADS_REFRESH_TOKEN are set
  • BING_ADS_CLIENT_SECRET is set (if using a confidential app)
  • OAuth token is valid (expires, may need refresh)
Rate limit exceeded

Bing Ads applies rate limits. The server handles common retries automatically. If you hit limits frequently:

  • Batch operations when possible
  • Reduce query frequency
  • Wait before retrying
Quality Score is 0

QS = 0 means keyword hasn't been shown enough times yet. Increase impressions or wait for more data.

License

MIT

Contributing

Contributions welcome! Please:

  1. Add tests for new features
  2. Update README
  3. Follow existing code style
  4. Tag releases

Support

  • Issues: GitHub issues for bugs/feature requests
  • Docs: See docs/ folder for detailed API reference
  • Community: GitHub Discussions

Built By

Mark Harnett — Demand generation leader and paid media practitioner building AI-powered ad management tools. This is the first comprehensive open-source Bing Ads MCP server — born from managing real campaigns across multiple accounts and wanting Claude to do the heavy lifting.

Built with production workloads in mind: resilient API calls (circuit breakers, retry with backoff, response truncation), full Quality Score diagnostics, and negative keyword management at scale.

Also by Mark: mcp-linkedin-ads -- LinkedIn Ads MCP server with 11 tools.

Last Updated: 2026-03-13

Keywords