# mcp-bing-ads

> MCP server for Microsoft Advertising (Bing Ads) API with campaign, ad group, keyword, and performance reporting. First comprehensive open-source Bing Ads MCP.

Latest version **1.3.3** (published 2026-11-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install mcp-bing-ads
pnpm add mcp-bing-ads
yarn add mcp-bing-ads
bun add mcp-bing-ads
```

Provides the command `mcp-bing-ads`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2026-11-14 |
| First published | 2026-03-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.18.0 |
| Dependencies | 6 |
| Unpacked size | 104.5 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Author | drak-marketing |
| Maintainers | drak-marketing |
| Keywords | mcp, model-context-protocol, microsoft-advertising, bing-ads, marketing, automation, claude, ad-management |

## Links

- npm: https://www.npmjs.com/package/mcp-bing-ads
- Repository: https://github.com/mharnett/mcp-bing-ads
- Homepage: https://github.com/mharnett/mcp-bing-ads#readme
- Issues: https://github.com/mharnett/mcp-bing-ads/issues
- npm.io page: https://npm.io/package/mcp-bing-ads

## Dependencies (6)

- [zod](https://npm.io/package/zod.md) ^3.22.4
- [pino](https://npm.io/package/pino.md) ^8.21.0
- [cockatiel](https://npm.io/package/cockatiel.md) ^3.2.1
- [pino-pretty](https://npm.io/package/pino-pretty.md) ^13.1.3
- [mcp-write-gate](https://npm.io/package/mcp-write-gate.md) ^1.0.0
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^0.5.0

## Recent versions

- 1.3.3 (latest) — 2026-11-14
- 1.3.2 — 2026-10-31
- 1.3.1 — 2026-10-30
- 1.2.0 — 2026-09-03
- 1.1.1 — 2026-07-09
- 1.1.0 — 2026-05-28
- 1.0.15 — 2026-04-09
- 1.0.14 — 2026-04-09
- 1.0.13 — 2026-04-09
- 1.0.12 — 2026-04-09
- 1.0.11 — 2026-04-09
- 1.0.10 — 2026-04-09
- 1.0.9 — 2026-04-09
- 1.0.8 — 2026-04-09
- 1.0.7 — 2026-04-09
- … 7 more at https://npm.io/package/mcp-bing-ads/versions

## README

# Bing Ads MCP Server

[![npm version](https://img.shields.io/npm/v/mcp-bing-ads)](https://www.npmjs.com/package/mcp-bing-ads)
[![npm downloads](https://img.shields.io/npm/dm/mcp-bing-ads)](https://www.npmjs.com/package/mcp-bing-ads)
[![GitHub stars](https://img.shields.io/github/stars/mharnett/mcp-bing-ads)](https://github.com/mharnett/mcp-bing-ads)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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

```bash
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](https://portal.azure.com/)
   - 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`:**
   ```bash
   cp config.example.json config.json
   ```

3. **Fill in your credentials:**
   ```json
   {
     "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):**
   ```bash
   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`):
```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
```typescript
// 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

```bash
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
```bash
npm test -- --run        # Single run
npm test -- --watch      # Watch mode
```

## Troubleshooting

### `Config file not found`
```bash
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](https://www.linkedin.com/in/markharnett/)** — 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](https://github.com/mharnett/mcp-linkedin-ads) -- LinkedIn Ads MCP server with 11 tools.

**Last Updated:** 2026-03-13

---
_Source: https://npm.io/package/mcp-bing-ads · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
