mcp-microsoft-ads

Inoffiziell – nicht mit Microsoft verbunden, von Microsoft unterstützt oder befürwortet. Dies ist ein Drittanbieter-MCP-Server (Model Context Protocol) für Microsoft Advertising. „MCP“ ist das offene Protokoll, das es einem KI-Assistenten (Claude oder einem anderen MCP-Client) ermöglicht, Tools gegen ein echtes System aufzurufen – hier Ihr Microsoft-Ads-Konto.

Der sicherheitsorientierte Microsoft-Ads-MCP: 47 Tools für Kampagnen-, Anzeigengruppen-, Keyword-, Negativ-Keyword-, Geo-Targeting-, Anzeigenzeitplan-, Erweiterungs-, Medien-, Zielgruppen- und Conversion-Ziel-Verwaltung sowie Leistungsberichte und Ad-Insight-Keyword-Recherche – entwickelt, damit ein KI-Assistent mit Schreibzugriff auf ein Live-Werbekonto nicht automatisch einen Blankoscheck erhält.

Warum „Sicherheit zuerst“

Jedes ändernde Tool ist standardmäßig deaktiviert. Das Aktivieren von Schreibvorgängen erfolgt über eine Umgebungsvariable, und selbst dann durchläuft jeder Schreibvorgang dieselbe mehrschichtige Absicherung, bevor ein einziger Aufruf die Microsoft-API erreicht:

1. MS_ADS_ENABLE_WRITES=true – ohne diese Einstellung verweigert jedes Schreib-Tool die Ausführung. Standardmäßig ist dies ein schreibgeschützter Server.

2. Entwurf → Bestätigung. Ein Schreib-Tool mutiert nie bei seinem eigenen Aufruf. Es gibt eine Vorschau zurück (eine draft_id und genau, was sich ändern würde); nichts wird wirksam, bis Sie – oder Ihr MCP-Client – confirm_and_apply(draft_id) aufrufen.

3. Ausgabenobergrenzen. Sowohl die Entwurfserstellung als auch das Anwenden lehnen Beträge ab, die über MS_ADS_MAX_DAILY_BUDGET (Standard 1000) oder MS_ADS_MAX_CPC (Standard 50) liegen, in der Währung des Kontos selbst, nicht in USD.

4. Fail-Closed-Schutz für Smart Bidding. Gebots-/Anpassungsschreibvorgänge sind auf manuelle Gebotsstrategien beschränkt (ManualCpc, EnhancedCpc, ManualCpv, ManualCpm, ManualCpa); eine unbekannte oder automatisierte Strategie (MaxConversions, TargetCpa, TargetRoas, …) wird abgelehnt, anstatt als sicher angenommen zu werden.

5. JSONL-Auditprotokoll. Jeder Entwurf und jede Anwendung wird an eine lokale, nur-append-fähige JSONL-Datei angehängt – eine Klartext-Aufzeichnung dessen, was dieser Server tatsächlich getan hat.

Unterstützt durch über 380 Offline-Tests (keine Live-API-Aufrufe), die die Absicherungen, die SOAP-Implementierungsdetails und den Entwurf/Bestätigungs-Lebenszyklus gegen Fakes testen.

Seien Sie ehrlich, was „Entwurf → Bestätigung“ nicht ist

Entwurf → Bestätigung ist ein Vorschau-Gate gegen Einzelaufruf-Unfälle – ein Tippfehler bei einem Gebot, ein Copy-Paste-Fehler, das Aufrufen des falschen Tools. Es ist keine Zugriffskontrolle mit menschlicher Genehmigung: Derselbe MCP-Client, der den Entwurf erstellt hat, kann confirm_and_apply unmittelbar danach aufrufen, ohne dass der Server eine menschliche Beteiligung verlangt. Wenn Sie möchten, dass ein Mensch jeden Schreibvorgang überprüft, muss dies durch Ihren eigenen Workflow durchgesetzt werden (ein separater Genehmigungsschritt, ein Nur-Mensch-Client usw.) – dieser Server übernimmt das nicht für Sie.

Ein Schreibvorgang wird separat hervorgehoben, weil die oben beschriebene mehrschichtige Geschichte ihn nicht vollständig begrenzen kann: apply_recommendation übergibt an eine von Microsoft festgelegte Mutation – Sie sehen nur die Empfehlungs-ID, nicht die Änderung selbst, sodass die tatsächliche finanzielle Auswirkung nicht von den Ausgabenobergrenzen dieses Servers im Voraus geprüft werden kann. Es bleibt erhalten (Microsofts Empfehlungen können nützlich sein), wird lautstark als Ausnahme gekennzeichnet und ist hinter beiden MS_ADS_ENABLE_WRITES und seiner eigenen separaten Flagge MS_ADS_ALLOW_APPLY_RECOMMENDATION geschaltet – sodass das allgemeine Aktivieren von Schreibvorgängen dieses Tool nicht automatisch aktiviert.

Was dieser Server nicht tut

• Keine Quality-Score-Diagnose.

• Kein automatisches Wiederholen/Backoff bei vorübergehenden API-Fehlern (ein fehlgeschlagener Aufruf schlägt fehl; Sie wiederholen).

• Basiert auf dem SOAP-Bing-Ads-SDK von Microsoft, das Microsoft als End-of-Life angekündigt hat – siehe unten.

Related MCP server: OpenAI Ads MCP

SOAP-End-of-Life und die REST-Roadmap

Dieser Server basiert auf dem bingads-SOAP-SDK. Microsoft hat angekündigt, dass SOAP am 2027-01-31 End-of-Life ist, und empfiehlt eine Migration vor 2026-10-01 (neue API-Funktionen werden ab dann nur noch als REST ausgeliefert). Siehe Microsofts Migrate to REST API Leitfaden und den Python SDK SOAP-to-REST migration guide. Die Portierung der Tools dieses Servers auf REST ist das Roadmap-Ziel – SOAP funktioniert heute noch und verschwindet erst zum EOL-Datum, aber planen Sie nicht langfristig damit.

Wie dies im Vergleich abschneidet

Vergleich zuletzt geprüft am 2026-08-24. Dieses Projekt beansprucht nicht, den genauen aktuellen Funktionsumfang der anderen Zeilen zu kennen, außer ob sie schreibgeschützt sind oder nicht – prüfen Sie das jeweilige Repo/die Doku des Projekts für Details. Die oben genannten Unterscheidungsmerkmale (optionale Schreibvorgänge, zweiphasiges Entwurf→Bestätigung, Ausgabenobergrenzen, Smart-Bidding-Fail-Closed-Schutz, JSONL-Auditprotokoll, über 380 Offline-Tests) sind das, worum dieses Projekt herum aufgebaut ist.

Installation

git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
cd mcp-microsoft-ads
python3 -m venv .venv  # requires Python >= 3.12
.venv/bin/pip install -e ".[dev]"

Die vollständige Einrichtung – Azure-App-Registrierung, Entwicklertoken, erste OAuth-Anmeldung – finden Sie in docs/setup.md. Dieser Abschnitt behandelt nur das Ausführen des Servers, sobald Anmeldeinformationen bereits vorhanden sind.

Anmeldeinformationen

Die Anmeldeinformationen liegen außerhalb des Repos in einer YAML-Datei (Standard ~/.mcp-microsoft-ads/credentials.yaml, überschreibbar mit MS_ADS_CREDENTIALS_PATH): developer_token, client_id, client_secret, refresh_token, customer_id, account_id, tenant.

Die sechs statischen Felder (alles außer refresh_token) können stattdessen als MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET, MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT-Umgebungsvariablen gesetzt werden – Umgebungsvariablen gewinnen gegenüber der Datei, wenn beide vorhanden sind. refresh_token ist nur in der Datei: Microsoft rotiert es bei jeder Verwendung, und ein rotiertes Token muss für den nächsten Lauf irgendwo gespeichert werden, was eine Umgebungsvariable nicht leisten kann. Der Server schreibt jede Rotation atomar zurück in die Anmeldedatei (eine .bak-Datei wird aufbewahrt).

Erster Start – Schritt-für-Schritt

1. Bootstrap-Anmeldung:

   .venv/bin/python -m mcp_microsoft_ads.reauth

   Führt eine interaktive OAuth-Anmeldung in Ihrem Browser durch und schreibt das resultierende refresh_token in die Anmeldedatei. Siehe docs/setup.md für die Azure-App-Registrierung und das Entwicklertoken, von denen dieser Schritt abhängt.

2. Starten Sie den Server schreibgeschützt (setzen Sie MS_ADS_ENABLE_WRITES noch nicht) und rufen Sie von Ihrem MCP-Client health_check, dann list_accounts und/oder get_account_info auf.

3. Bestätigen Sie, dass das Konto das richtige ist – prüfen Sie die Kontonummer, den Kontonamen und die Kontowährung, die von diesen Aufrufen zurückgegeben werden, gegen das Konto, das Sie diesem Server zugreifen lassen möchten. Die unten genannten Ausgabenobergrenzen werden in der Währung dieses Kontos durchgesetzt, daher ist eine Währungsabweichung es wert, erkannt zu werden, bevor Schreibvorgänge jemals aktiviert werden.

4. Erst dann setzen Sie MS_ADS_ENABLE_WRITES=true (und, falls gewünscht, MS_ADS_ALLOW_APPLY_RECOMMENDATION=true) und starten den Server neu.

MCP-Client-Konfiguration

Beide Konfigurationen gehen davon aus, dass sich die venv oben unter ~/mcp-microsoft-ads/.venv befindet – ersetzen Sie das durch den tatsächlichen absoluten Pfad auf Ihrem Rechner (beide Clients benötigen einen absoluten Pfad, nicht ~).

Claude Code (.mcp.json in Ihrem Projekt oder über claude mcp add):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Zeigen Sie nicht zwei gleichzeitige Clients auf dieselbe Anmeldedatei

Das Teilen einer Anmeldedatei zwischen gleichzeitigen Clients wird nicht unterstützt. Das refresh_token ist eine rotierende, gemeinsame, veränderbare Datei: Jede Aktualisierung erzeugt ein neues Token und macht das alte sofort ungültig, und das Lesen-Ändern-Schreiben, das die Rotation speichert, kann auf dieser Ebene nicht sicher über zwei separate Prozesse serialisiert werden. Zwei Clients, die gleichzeitig aus derselben Datei aktualisieren, können sich gegenseitig mit einem ungültigen Token stranden. Wenn Sie mehr als einen gleichzeitigen Client möchten (z. B. Claude Code und Claude Desktop gleichzeitig geöffnet), geben Sie jedem Client eine eigene Anmeldedatei und eine eigene Azure-App-Registrierung – setzen Sie MS_ADS_CREDENTIALS_PATH unterschiedlich pro Client und bootstrappen Sie jeden mit seinem eigenen reauth-Lauf.

Umgebungsvariablen

Hinweis zur Währung: MS_ADS_MAX_DAILY_BUDGET und MS_ADS_MAX_CPC werden direkt mit Beträgen in der eigenen Währung des Kontos verglichen, nicht in USD umgerechnet. Eine Obergrenze von 1000 bedeutet 1000 Einheiten der Währung, in der das Konto geführt wird.

Test / Lint

.venv/bin/python -m pytest -q     # offline test suite, ~370 tests, no live API calls
.venv/bin/python -m ruff check .  # lint

Dokumentation

• docs/setup.md — Azure-App-Registrierung, Entwicklertoken, vollständige Einrichtung.

• SECURITY.md — wie Sie eine Sicherheitslücke melden.

• CHANGELOG.md — Versionshistorie.

Lizenz und Support

MIT-lizenziert — siehe LICENSE. Dies ist ein Best-Effort-, unbezahltes Open-Source-Projekt: keine SLA, keine garantierte Antwortzeit. Issues werden nach bestem Ermessen beobachtet und triagiert.