mcp-microsoft-ads 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcp_microsoft_ads-1.1.0/LICENSE +21 -0
- mcp_microsoft_ads-1.1.0/PKG-INFO +360 -0
- mcp_microsoft_ads-1.1.0/README.md +326 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/__init__.py +1 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/app.py +9 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/audit.py +22 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/auth.py +309 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/client.py +131 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/rails.py +337 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/reauth.py +251 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/reporting_core.py +135 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/server.py +46 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/settings.py +157 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/setup_wizard.py +88 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/__init__.py +0 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/adgroups_write.py +86 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/ads_write.py +79 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/audiences.py +139 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/campaigns_write.py +143 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/confirm.py +11 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/conversions.py +143 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/entities.py +53 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/extensions_write.py +193 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/geo_read.py +46 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/geo_write.py +55 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/infra.py +47 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/insight.py +202 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/keywords_write.py +124 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/media.py +109 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/negatives_read.py +39 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/negatives_write.py +137 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/pmax.py +269 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/reads_misc.py +87 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/remove.py +59 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/reporting.py +138 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/schedule.py +154 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/tools/status.py +102 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/util.py +13 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads/verify.py +22 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/PKG-INFO +360 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/SOURCES.txt +80 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/dependency_links.txt +1 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/entry_points.txt +2 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/requires.txt +11 -0
- mcp_microsoft_ads-1.1.0/mcp_microsoft_ads.egg-info/top_level.txt +1 -0
- mcp_microsoft_ads-1.1.0/pyproject.toml +56 -0
- mcp_microsoft_ads-1.1.0/setup.cfg +4 -0
- mcp_microsoft_ads-1.1.0/tests/test_adgroups_write.py +161 -0
- mcp_microsoft_ads-1.1.0/tests/test_ads_write.py +104 -0
- mcp_microsoft_ads-1.1.0/tests/test_audiences.py +167 -0
- mcp_microsoft_ads-1.1.0/tests/test_audit.py +84 -0
- mcp_microsoft_ads-1.1.0/tests/test_auth.py +407 -0
- mcp_microsoft_ads-1.1.0/tests/test_campaigns_write.py +140 -0
- mcp_microsoft_ads-1.1.0/tests/test_client.py +97 -0
- mcp_microsoft_ads-1.1.0/tests/test_conversions.py +207 -0
- mcp_microsoft_ads-1.1.0/tests/test_entities.py +62 -0
- mcp_microsoft_ads-1.1.0/tests/test_extensions_write.py +230 -0
- mcp_microsoft_ads-1.1.0/tests/test_geo_read.py +28 -0
- mcp_microsoft_ads-1.1.0/tests/test_geo_write.py +91 -0
- mcp_microsoft_ads-1.1.0/tests/test_infra.py +78 -0
- mcp_microsoft_ads-1.1.0/tests/test_insight.py +140 -0
- mcp_microsoft_ads-1.1.0/tests/test_keywords_write.py +193 -0
- mcp_microsoft_ads-1.1.0/tests/test_marketer_usability.py +96 -0
- mcp_microsoft_ads-1.1.0/tests/test_media.py +86 -0
- mcp_microsoft_ads-1.1.0/tests/test_negatives_read.py +54 -0
- mcp_microsoft_ads-1.1.0/tests/test_negatives_write.py +142 -0
- mcp_microsoft_ads-1.1.0/tests/test_pmax.py +338 -0
- mcp_microsoft_ads-1.1.0/tests/test_rails.py +503 -0
- mcp_microsoft_ads-1.1.0/tests/test_reads_misc.py +111 -0
- mcp_microsoft_ads-1.1.0/tests/test_reauth.py +356 -0
- mcp_microsoft_ads-1.1.0/tests/test_remove.py +88 -0
- mcp_microsoft_ads-1.1.0/tests/test_reporting_core.py +63 -0
- mcp_microsoft_ads-1.1.0/tests/test_reporting_periods.py +6 -0
- mcp_microsoft_ads-1.1.0/tests/test_reporting_tools.py +40 -0
- mcp_microsoft_ads-1.1.0/tests/test_schedule.py +257 -0
- mcp_microsoft_ads-1.1.0/tests/test_security_regressions.py +264 -0
- mcp_microsoft_ads-1.1.0/tests/test_server_smoke.py +23 -0
- mcp_microsoft_ads-1.1.0/tests/test_settings.py +270 -0
- mcp_microsoft_ads-1.1.0/tests/test_status.py +55 -0
- mcp_microsoft_ads-1.1.0/tests/test_stranger_defaults.py +95 -0
- mcp_microsoft_ads-1.1.0/tests/test_util.py +16 -0
- mcp_microsoft_ads-1.1.0/tests/test_verify.py +21 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alex Murtha
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-microsoft-ads
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Safety-first MCP server for the Microsoft Advertising API: opt-in writes, two-phase draft/confirm, spend rails, Smart Bidding guards, audit log.
|
|
5
|
+
Author-email: Alex Murtha <wvuhskr@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/wvuhskr/mcp-microsoft-ads
|
|
8
|
+
Project-URL: Repository, https://github.com/wvuhskr/mcp-microsoft-ads
|
|
9
|
+
Project-URL: Issues, https://github.com/wvuhskr/mcp-microsoft-ads/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/wvuhskr/mcp-microsoft-ads/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: mcp,model-context-protocol,microsoft-ads,bing-ads,advertising,paid-media,ppc,llm
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
20
|
+
Requires-Python: >=3.12
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: bingads==13.0.29
|
|
24
|
+
Requires-Dist: mcp<3,>=1.30.0
|
|
25
|
+
Requires-Dist: pyyaml>=6.0.3
|
|
26
|
+
Requires-Dist: pillow>=12.3.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
30
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
31
|
+
Requires-Dist: bandit>=1.9.4; extra == "dev"
|
|
32
|
+
Requires-Dist: pip-audit>=2.10.1; extra == "dev"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# mcp-microsoft-ads
|
|
36
|
+
|
|
37
|
+
**Unofficial — not affiliated with, endorsed by, or supported by Microsoft.** This is
|
|
38
|
+
a third-party MCP (Model Context Protocol) server for Microsoft Advertising. "MCP" is
|
|
39
|
+
the open protocol that lets an AI assistant (Claude, or any other MCP client) call
|
|
40
|
+
tools against a real system — here, your Microsoft Ads account.
|
|
41
|
+
|
|
42
|
+
**In plain terms:** this connects an AI assistant such as Claude to your Microsoft
|
|
43
|
+
Advertising (Bing Ads) account, so you can ask questions about performance in plain
|
|
44
|
+
English and, if you choose to allow it, have the assistant make changes for you. It
|
|
45
|
+
starts read-only. Changes are something you switch on, and every change is previewed
|
|
46
|
+
before it happens.
|
|
47
|
+
|
|
48
|
+
48 tools cover reporting, keyword research, and campaign, ad group, keyword,
|
|
49
|
+
negative-keyword, location, ad-schedule, extension, image, audience, and
|
|
50
|
+
conversion-goal management.
|
|
51
|
+
|
|
52
|
+
## What you can ask
|
|
53
|
+
|
|
54
|
+
Once it is connected, talk to your assistant normally. For example:
|
|
55
|
+
|
|
56
|
+
- "How did each campaign do over the last 30 days? Show spend, conversions and cost
|
|
57
|
+
per conversion."
|
|
58
|
+
- "Which search terms spent money last month without converting? Check them against
|
|
59
|
+
my existing negative keyword lists and suggest only new negatives."
|
|
60
|
+
- "Split last month's conversions by conversion goal for each campaign."
|
|
61
|
+
- "What was my impression share last quarter, and did I lose more to budget or to rank?"
|
|
62
|
+
- "Find keyword ideas for 'emergency plumber' and estimate clicks at a $12 bid."
|
|
63
|
+
- "Are any ads or keywords disapproved?"
|
|
64
|
+
- "Pause the ad group called Test, and show me the change before you make it."
|
|
65
|
+
(needs changes switched on, see [Turning on changes](#turning-on-changes))
|
|
66
|
+
|
|
67
|
+
Every report comes back with a source note: the account, the report type, the date
|
|
68
|
+
range, the columns pulled, and how conversions were counted.
|
|
69
|
+
|
|
70
|
+
## Quick start
|
|
71
|
+
|
|
72
|
+
You need a Microsoft Advertising account and about 20 minutes, most of it on
|
|
73
|
+
Microsoft's side. All commands below go in a terminal (the Terminal app on a Mac,
|
|
74
|
+
PowerShell on Windows).
|
|
75
|
+
|
|
76
|
+
1. **Install uv**, a small free tool that downloads and runs this server for you. One
|
|
77
|
+
command, from <https://docs.astral.sh/uv/getting-started/installation/>.
|
|
78
|
+
2. **Get two things from Microsoft**: a developer token and an "app registration".
|
|
79
|
+
[docs/setup.md](docs/setup.md) steps 2 and 3 walk through both, click by click.
|
|
80
|
+
This is the slow part, and you only do it once.
|
|
81
|
+
3. **Run the guided setup.** It asks for the values from step 2, opens the Microsoft
|
|
82
|
+
sign-in, and saves everything in a private file on your computer:
|
|
83
|
+
```bash
|
|
84
|
+
uvx --from git+https://github.com/wvuhskr/mcp-microsoft-ads mcp-microsoft-ads setup
|
|
85
|
+
```
|
|
86
|
+
4. **Connect your assistant.** Setup ends by printing a short block of text. Paste it
|
|
87
|
+
into your assistant's connector settings ([MCP client configuration](#mcp-client-configuration)
|
|
88
|
+
shows where) and restart the assistant.
|
|
89
|
+
5. **Check it.** Ask the assistant: "Run a Microsoft Ads health check and list my
|
|
90
|
+
accounts." Confirm the account name and currency are the ones you expect.
|
|
91
|
+
|
|
92
|
+
If the sign-in ever stops working (Microsoft asks for a fresh sign-in from time to
|
|
93
|
+
time), run the same command with `reauth` in place of `setup`.
|
|
94
|
+
|
|
95
|
+
## The tools
|
|
96
|
+
|
|
97
|
+
You never call these by name; the assistant picks them. The list is here so you know
|
|
98
|
+
what is possible.
|
|
99
|
+
|
|
100
|
+
**Look, never change (always available)**
|
|
101
|
+
|
|
102
|
+
| Tool | What it does |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `health_check`, `list_accounts`, `get_account_info` | Confirm the connection and which account you are in |
|
|
105
|
+
| `get_campaign_performance`, `get_ad_performance`, `get_keyword_performance` | Ready-made performance reports for the last 7, 14 or 30 days |
|
|
106
|
+
| `get_search_terms` | What people actually typed before clicking |
|
|
107
|
+
| `get_geo_performance` | Performance by country, state, metro area and city |
|
|
108
|
+
| `run_report`, `describe_report` | Build-your-own report: any Microsoft report, any columns, any dates. `describe_report` lists what is available |
|
|
109
|
+
| `get_entities` | Current settings of campaigns, ad groups, keywords, ads, asset groups, schedules and locations |
|
|
110
|
+
| `get_negative_keywords` | Campaign negatives plus every shared negative list |
|
|
111
|
+
| `list_extensions`, `get_conversion_actions`, `get_policy_issues` | Extensions, conversion goals, disapproved ads and keywords |
|
|
112
|
+
| `discover_keywords`, `get_keyword_forecasts` | Keyword ideas and traffic estimates |
|
|
113
|
+
| `search_geo_targets` | Find a location to target or exclude |
|
|
114
|
+
| `list_recommendations` | Microsoft's recommendations (not available on every account) |
|
|
115
|
+
|
|
116
|
+
**Make changes (only when you switch changes on; each one is previewed first)**
|
|
117
|
+
|
|
118
|
+
| Tool | What it does |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `confirm_and_apply` | Carries out a previewed change. Nothing changes without it |
|
|
121
|
+
| `pause_entity`, `enable_entity`, `remove_entity` | Pause, enable or delete a campaign, ad group, keyword or ad |
|
|
122
|
+
| `update_campaign`, `update_ad_group`, `update_keyword_bid` | Budget, status, target cost per conversion, manual bids |
|
|
123
|
+
| `draft_campaign`, `create_pmax_campaign`, `create_portfolio_bidding_strategy` | New campaigns (always created paused) and shared bid strategies |
|
|
124
|
+
| `draft_responsive_search_ad`, `draft_keywords`, `remove_keywords` | New ads and keywords (keywords created paused) |
|
|
125
|
+
| `add_negative_keywords`, `remove_negative_keywords` | Negatives on a campaign, ad group or shared list; duplicates are skipped |
|
|
126
|
+
| `set_campaign_schedule` | Replace a campaign's ad schedule |
|
|
127
|
+
| `exclude_geo_target`, `remove_geo_target` | Location exclusions |
|
|
128
|
+
| `draft_sitelinks`, `create_callouts`, `create_structured_snippets`, `remove_extension` | Ad extensions |
|
|
129
|
+
| `upload_image_asset` | Add an image to the account's library |
|
|
130
|
+
| `create_custom_audience`, `add_audience_targeting` | Remarketing lists and audience targeting |
|
|
131
|
+
| `create_conversion_action`, `set_conversion_action_primary_status` | Conversion goals |
|
|
132
|
+
| `apply_recommendation`, `dismiss_recommendation` | Act on Microsoft's recommendations (extra switch required) |
|
|
133
|
+
|
|
134
|
+
## Why "safety-first"
|
|
135
|
+
|
|
136
|
+
Every mutating tool is **off by default**. Turning writes on is one env var, and even
|
|
137
|
+
then every write goes through the same layered gate before a single call reaches
|
|
138
|
+
Microsoft's API:
|
|
139
|
+
|
|
140
|
+
1. **`MS_ADS_ENABLE_WRITES=true`** — without it, every write tool refuses to run.
|
|
141
|
+
Out of the box this is a read-only server.
|
|
142
|
+
2. **Draft → confirm.** A write tool never mutates on its own call. It returns a
|
|
143
|
+
preview (a `draft_id` and exactly what would change); nothing lands until you — or
|
|
144
|
+
your MCP client — calls `confirm_and_apply(draft_id)`.
|
|
145
|
+
3. **Spend ceilings.** Draft creation and apply both reject amounts above
|
|
146
|
+
`MS_ADS_MAX_DAILY_BUDGET` (default 1000) or `MS_ADS_MAX_CPC` (default 50), **in the
|
|
147
|
+
account's own currency**, not USD.
|
|
148
|
+
4. **Smart Bidding fail-closed guards.** Bid/adjustment writes are allowlisted to
|
|
149
|
+
manual bidding strategies (`ManualCpc`, `EnhancedCpc`, `ManualCpv`, `ManualCpm`,
|
|
150
|
+
`ManualCpa`); an unrecognized or automated strategy (`MaxConversions`, `TargetCpa`,
|
|
151
|
+
`TargetRoas`, …) is refused rather than assumed safe.
|
|
152
|
+
5. **JSONL audit log.** Every draft and every apply is appended to a local,
|
|
153
|
+
append-only JSONL file — a plain-text paper trail of what this server actually did.
|
|
154
|
+
|
|
155
|
+
Backed by 420+ offline tests (no live API calls) that exercise the rails, the SOAP
|
|
156
|
+
plumbing quirks, and the draft/confirm lifecycle against fakes.
|
|
157
|
+
|
|
158
|
+
### Be honest about what "draft → confirm" is *not*
|
|
159
|
+
|
|
160
|
+
Draft → confirm is a **preview gate against single-call accidents** — a typo in a bid,
|
|
161
|
+
a copy-paste mistake, calling the wrong tool. It is **not human-approval access
|
|
162
|
+
control**: the same MCP client that created the draft can call `confirm_and_apply`
|
|
163
|
+
immediately afterward, with no human in the loop required by the server. If you want
|
|
164
|
+
a human to review every write, that has to be enforced by your own workflow (a
|
|
165
|
+
separate approval step, a human-only client, etc.) — this server doesn't do it for you.
|
|
166
|
+
|
|
167
|
+
One write is called out separately because the layered story above can't fully bound
|
|
168
|
+
it: **`apply_recommendation`** hands off to a Microsoft-decided mutation — you preview
|
|
169
|
+
only the recommendation ID, not the change itself, so the actual monetary effect isn't
|
|
170
|
+
something this server's spend ceilings can check in advance. It's kept (Microsoft's
|
|
171
|
+
recommendations can be useful), loudly labeled as the exception it is, and gated
|
|
172
|
+
behind **both** `MS_ADS_ENABLE_WRITES` and its own separate flag,
|
|
173
|
+
`MS_ADS_ALLOW_APPLY_RECOMMENDATION` — so turning on writes generally does not turn
|
|
174
|
+
this one on.
|
|
175
|
+
|
|
176
|
+
### What this server does *not* do
|
|
177
|
+
|
|
178
|
+
- No Quality Score diagnostics.
|
|
179
|
+
- No automatic retry/backoff on transient API failures (a failed call fails; you
|
|
180
|
+
retry).
|
|
181
|
+
- Built on Microsoft's SOAP Bing Ads SDK, which Microsoft has announced end-of-life —
|
|
182
|
+
see below.
|
|
183
|
+
|
|
184
|
+
## SOAP end-of-life and the REST roadmap
|
|
185
|
+
|
|
186
|
+
This server is built on the `bingads` SOAP SDK. Microsoft has announced that SOAP is
|
|
187
|
+
end-of-life on **2027-01-31**, and recommends migrating before **2026-10-01** (new
|
|
188
|
+
API features ship REST-only from then). See Microsoft's
|
|
189
|
+
[Migrate to REST API](https://learn.microsoft.com/en-us/advertising/guides/migrate-to-rest?view=bingads-13)
|
|
190
|
+
guide and the
|
|
191
|
+
[Python SDK SOAP-to-REST migration guide](https://learn.microsoft.com/en-us/advertising/guides/python-sdk-migration-soap-to-rest?view=bingads-13).
|
|
192
|
+
Porting this server's tools to REST is the roadmap item — SOAP still works today and
|
|
193
|
+
isn't going away until the EOL date, but don't plan around it long-term.
|
|
194
|
+
|
|
195
|
+
## How this compares
|
|
196
|
+
|
|
197
|
+
| | write access | write safety layer | notes |
|
|
198
|
+
|---|---|---|---|
|
|
199
|
+
| **mcp-microsoft-ads** (this project) | yes, opt-in | draft→confirm + spend ceilings + Smart-Bidding guards + audit log | SOAP today, REST planned |
|
|
200
|
+
| [mharnett/mcp-bing-ads](https://github.com/mharnett/mcp-bing-ads) | — | — | see their repo for current scope |
|
|
201
|
+
| bit-of-a-shambles Bing Ads MCP server | — | — | see that project's repo for current scope |
|
|
202
|
+
| CData Microsoft Ads MCP connector | read-only | n/a | no write path |
|
|
203
|
+
| Microsoft's official hosted MCP | — | — | see Microsoft's docs for current scope |
|
|
204
|
+
|
|
205
|
+
Comparison last checked 2026-08-24. This project doesn't claim to know the exact
|
|
206
|
+
current feature set of the other rows
|
|
207
|
+
beyond what's read-only vs. not — check each project's own repo/docs for details. The
|
|
208
|
+
differentiators above (opt-in writes, two-phase draft→confirm, spend ceilings,
|
|
209
|
+
Smart-Bidding fail-closed guards, JSONL audit log, 420+ offline tests) are what this
|
|
210
|
+
project is built around.
|
|
211
|
+
|
|
212
|
+
## Install for development
|
|
213
|
+
|
|
214
|
+
Most people should use the [Quick start](#quick-start) instead. To work on the code:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
|
|
218
|
+
cd mcp-microsoft-ads
|
|
219
|
+
python3 -m venv .venv # requires Python >= 3.12
|
|
220
|
+
.venv/bin/pip install -e ".[dev]"
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
In a clone, `.venv/bin/mcp-microsoft-ads setup` runs the same guided setup.
|
|
224
|
+
|
|
225
|
+
### Credentials
|
|
226
|
+
|
|
227
|
+
Credentials live outside the repo, in a YAML file (default
|
|
228
|
+
`~/.mcp-microsoft-ads/credentials.yaml`, override with `MS_ADS_CREDENTIALS_PATH`):
|
|
229
|
+
`developer_token`, `client_id`, `client_secret`, `refresh_token`, `customer_id`,
|
|
230
|
+
`account_id`, `tenant`.
|
|
231
|
+
|
|
232
|
+
The six static fields (everything except `refresh_token`) can instead be set as
|
|
233
|
+
`MS_ADS_DEVELOPER_TOKEN`, `MS_ADS_CLIENT_ID`, `MS_ADS_CLIENT_SECRET`,
|
|
234
|
+
`MS_ADS_CUSTOMER_ID`, `MS_ADS_ACCOUNT_ID`, `MS_ADS_TENANT` env vars — env wins over the
|
|
235
|
+
file when both are present. `refresh_token` is file-only: Microsoft rotates it on
|
|
236
|
+
every use, and a rotated token has to be persisted somewhere for the next run, which
|
|
237
|
+
an env var can't do. The server persists each rotation back to the credentials file
|
|
238
|
+
atomically (a `.bak` is kept). Both replacement files are created with
|
|
239
|
+
owner-only access before any credential content is written. Rotation changes only
|
|
240
|
+
the refresh-token value; unusual YAML aliases or block values may be rewritten
|
|
241
|
+
without their original comments to preserve the credential values safely.
|
|
242
|
+
|
|
243
|
+
### Image upload safety
|
|
244
|
+
|
|
245
|
+
`upload_image_asset` accepts valid PNG or JPEG files only. Local safety limits
|
|
246
|
+
are 5 MiB per file and 20 million pixels; these are this server's limits, not
|
|
247
|
+
Microsoft account limits. Animated and malformed images are rejected locally.
|
|
248
|
+
The preview includes a SHA-256 digest, a fingerprint of the file's contents.
|
|
249
|
+
Changing the file after preview requires a new draft. Validated bytes are uploaded
|
|
250
|
+
unchanged, including image metadata, so use assets intended for advertising.
|
|
251
|
+
|
|
252
|
+
### Supported tool library versions
|
|
253
|
+
|
|
254
|
+
The Model Context Protocol (MCP) library must be at least 1.30.0 and below 3.
|
|
255
|
+
The automated checks test the oldest supported version and the current version.
|
|
256
|
+
Intentional safety refusals and partial-write warnings remain visible to the
|
|
257
|
+
assistant in both library generations; unexpected errors retain the library's
|
|
258
|
+
normal handling.
|
|
259
|
+
|
|
260
|
+
## Turning on changes
|
|
261
|
+
|
|
262
|
+
Out of the box the server can only look. To let the assistant make changes:
|
|
263
|
+
|
|
264
|
+
1. **Confirm the account first.** While still read-only, have the assistant run
|
|
265
|
+
`health_check`, then `list_accounts` and `get_account_info`. Check the account ID,
|
|
266
|
+
name and currency against the account you mean. The spending limits below are
|
|
267
|
+
enforced in that account's currency.
|
|
268
|
+
2. **Add the switch** to the connector block (see the next section) and restart the
|
|
269
|
+
assistant: `MS_ADS_ENABLE_WRITES` set to `true`. Optionally lower the spending
|
|
270
|
+
limits `MS_ADS_MAX_DAILY_BUDGET` and `MS_ADS_MAX_CPC` to fit your account.
|
|
271
|
+
3. **Optional house rules.** Copy [advertiser.example.yaml](advertiser.example.yaml) to
|
|
272
|
+
`~/.mcp-microsoft-ads/advertiser.yaml` to ban words from ad copy, set your website,
|
|
273
|
+
and keep the "no Performance Max campaign without a target" rule on.
|
|
274
|
+
|
|
275
|
+
## MCP client configuration
|
|
276
|
+
|
|
277
|
+
This is the block the guided setup prints. It tells your assistant how to start the
|
|
278
|
+
server.
|
|
279
|
+
|
|
280
|
+
**Claude Desktop**: Settings > Developer > Edit Config opens
|
|
281
|
+
`claude_desktop_config.json`. **Claude Code**: put it in `.mcp.json` in your project.
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{
|
|
285
|
+
"mcpServers": {
|
|
286
|
+
"microsoft-ads": {
|
|
287
|
+
"command": "uvx",
|
|
288
|
+
"args": ["--from", "git+https://github.com/wvuhskr/mcp-microsoft-ads", "mcp-microsoft-ads"]
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
With changes switched on, the same block gains an `env` section:
|
|
295
|
+
|
|
296
|
+
```json
|
|
297
|
+
{
|
|
298
|
+
"mcpServers": {
|
|
299
|
+
"microsoft-ads": {
|
|
300
|
+
"command": "uvx",
|
|
301
|
+
"args": ["--from", "git+https://github.com/wvuhskr/mcp-microsoft-ads", "mcp-microsoft-ads"],
|
|
302
|
+
"env": { "MS_ADS_ENABLE_WRITES": "true", "MS_ADS_MAX_DAILY_BUDGET": "500" }
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
If your assistant reports it cannot find `uvx`, replace `"uvx"` with the full path
|
|
309
|
+
that `which uvx` (Mac/Linux) or `where uvx` (Windows) prints in a terminal. Working
|
|
310
|
+
from a clone instead: use `"command": "/full/path/to/mcp-microsoft-ads/.venv/bin/mcp-microsoft-ads"`
|
|
311
|
+
with no `args`.
|
|
312
|
+
|
|
313
|
+
### Several assistant sessions at once
|
|
314
|
+
|
|
315
|
+
Each open assistant session starts its own copy of this server, and they can all share
|
|
316
|
+
one credentials file on the same computer. Microsoft issues a new `refresh_token` on
|
|
317
|
+
each refresh but does not revoke the earlier ones when it does
|
|
318
|
+
([Microsoft's refresh-token documentation](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens)),
|
|
319
|
+
so when two sessions refresh close together the newer token simply replaces the other
|
|
320
|
+
on disk. Each write is atomic, so the file always holds one complete, working token.
|
|
321
|
+
A file with no usable token at all is still refused rather than overwritten.
|
|
322
|
+
|
|
323
|
+
## Environment variables
|
|
324
|
+
|
|
325
|
+
| Var | Default | Purpose |
|
|
326
|
+
|---|---|---|
|
|
327
|
+
| `MS_ADS_CREDENTIALS_PATH` | `~/.mcp-microsoft-ads/credentials.yaml` | credentials file location |
|
|
328
|
+
| `MS_ADS_ADVERTISER_CONFIG` | `~/.mcp-microsoft-ads/advertiser.yaml` | optional advertiser settings (blocked terms, advertiser domain, keyword-research defaults) — missing file means defaults |
|
|
329
|
+
| `MS_ADS_AUDIT_PATH` | `~/.mcp-microsoft-ads/audit.jsonl` | JSONL audit log location |
|
|
330
|
+
| `MS_ADS_ENABLE_WRITES` | `false` | master switch for all mutating tools |
|
|
331
|
+
| `MS_ADS_ALLOW_APPLY_RECOMMENDATION` | `false` | second, separate switch required (in addition to `MS_ADS_ENABLE_WRITES`) for `apply_recommendation` specifically |
|
|
332
|
+
| `MS_ADS_MAX_DAILY_BUDGET` | `1000` | daily-budget rail ceiling, **in the account's own currency** |
|
|
333
|
+
| `MS_ADS_MAX_CPC` | `50` | bid/tCPA rail ceiling, **in the account's own currency** |
|
|
334
|
+
| `MS_ADS_DRAFT_TTL_SECONDS` | `3600` | how long a draft stays valid before `confirm_and_apply` refuses it as stale |
|
|
335
|
+
| `MS_ADS_DEVELOPER_TOKEN`, `MS_ADS_CLIENT_ID`, `MS_ADS_CLIENT_SECRET`, `MS_ADS_CUSTOMER_ID`, `MS_ADS_ACCOUNT_ID`, `MS_ADS_TENANT` | — | the six static credential fields; env wins over the credentials file when both are set |
|
|
336
|
+
|
|
337
|
+
**Currency note:** `MS_ADS_MAX_DAILY_BUDGET` and `MS_ADS_MAX_CPC` are compared directly
|
|
338
|
+
against amounts in the account's own currency, not converted to or from USD. A `1000`
|
|
339
|
+
ceiling means 1000 units of whatever currency the account is denominated in.
|
|
340
|
+
|
|
341
|
+
## Test / lint
|
|
342
|
+
|
|
343
|
+
```bash
|
|
344
|
+
.venv/bin/python -m pytest -q # offline test suite, 420+ tests, no live API calls
|
|
345
|
+
.venv/bin/python -m ruff check . # lint
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
## Documentation
|
|
349
|
+
|
|
350
|
+
- [docs/setup.md](docs/setup.md) — Azure app registration, developer token, full
|
|
351
|
+
bootstrap.
|
|
352
|
+
- [advertiser.example.yaml](advertiser.example.yaml) — optional house rules, with comments.
|
|
353
|
+
- [SECURITY.md](SECURITY.md) — how to report a vulnerability.
|
|
354
|
+
- [CHANGELOG.md](CHANGELOG.md) — release history.
|
|
355
|
+
|
|
356
|
+
## License and support
|
|
357
|
+
|
|
358
|
+
MIT-licensed — see [LICENSE](LICENSE). This is a best-effort, unpaid open-source
|
|
359
|
+
project: no SLA, no guaranteed response time. Issues are watched and triaged on a
|
|
360
|
+
best-effort basis.
|