Microsoft Advertising MCP Connector

Claude.ai カスタムコネクタ向けのスタンドアロン True Model B MCP サーバー。1 人のオペレーターは複数の Microsoft アカウントを接続できます。各接続は、複数の Microsoft Advertising 顧客と広告アカウントを表示できます。

これは Google All-in-One コネクタの一部ではありません。このプロジェクトに対するランタイム依存関係はなく、Firestore コレクションの共有も、OAuth トークンの共有もありません。

Claude.ai
   │  MCP OAuth 2.1
   ▼
operatorId
   ├── Microsoft Connection A → customers → advertising accounts → campaigns / reports
   ├── Microsoft Connection B
   └── Microsoft Connection C

MCP JWT の sub は常に内部の operatorId です。Microsoft OpenID の sub は bing_mcp_microsoft_connections.microsoftSubjectId にのみ存在します。電子メールは表示用メタデータであり、認可キーになることは決してありません。

アーキテクチャ

• Next.js 15 App Router + mcp-handler による /mcp での Streamable HTTP

• PKCE S256、DCR、Claude CIMD を使用した MCP OAuth 2.1

• Microsoft Entra 認可コード フロー (common テナント)

• Microsoft Advertising REST v13 (SOAP ではありません)

• 名前付き Firestore データベース bing-mcp-v1

• 保存時の AES-256-GCM による更新トークンの暗号化

• Cloud Run (ステートレス、$PORT で待ち受け)

Related MCP server: Bing Ads MCP Server

資格情報 (これらは別物です)

環境

.env.example を .env にコピーします。.env をコミットしないでください。

必須:

APP_BASE_URL
MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
MICROSOFT_REDIRECT_URI
MICROSOFT_ADS_DEVELOPER_TOKEN
MCP_TOKEN_SECRET
OAUTH_STATE_SECRET
TOKEN_ENCRYPTION_KEY
FIRESTORE_PROJECT_ID
FIRESTORE_DATABASE_ID=bing-mcp-v1

FIRESTORE_DATABASE_ID は bing-mcp-v1 である必要があります。起動時に (default) と gconnect-mcp-all-v1 は拒否されます。

Microsoft Entra アプリ登録

1. Microsoft Entra アプリの登録 を開きます。

2. 登録を作成します。

3. サポートされるアカウントの種類: 任意の組織ディレクトリのアカウントと個人用 Microsoft アカウント (common が機能するため)。

4. Web リダイレクト URI を追加します: {APP_BASE_URL}/oauth/microsoft/callback (ローカル例: http://localhost:3000/oauth/microsoft/callback)。

5. クライアントシークレットを作成し、MICROSOFT_CLIENT_SECRET に保存します。

6. API のアクセス許可: Microsoft Advertising の委任スコープ https://ads.microsoft.com/msads.manage。さらに、openid、profile、email、offline_access も要求します。

7. テナントで必要な場合は、管理者の同意を付与します。

公式ガイド:

• OAuth を使用した認証

• ユーザーの同意を要求する

開発者トークン

Microsoft Advertising Developer Settings から Microsoft Advertising 開発者トークンを取得します。サンドボックストークンは自己発行できますが、本番トークンは Microsoft の承認が必要です。

このトークンはアプリケーションの資格情報です。Advertising REST 呼び出しでは DeveloperToken ヘッダーとして送信されます。オペレーターごとに保存されることはなく、MCP の出力やログに表示されることもあってはなりません。

ローカル開発

npm install
npm test
npm run typecheck
npm run dev

• ヘルスチェック: GET http://localhost:3000/health

• MCP: http://localhost:3000/mcp

• Microsoft コールバック: http://localhost:3000/oauth/microsoft/callback

Claude.ai で {APP_BASE_URL}/mcp を指すカスタムコネクタを追加します。Claude が MCP OAuth を完了すると、サーバーはブラウザーを Microsoft のログインにリダイレクトします。同意後、Claude に戻ります。

ローカルでの Firestore: Application Default Credentials (gcloud auth application-default login) と FIRESTORE_PROJECT_ID の組み合わせ、または FIRESTORE_EMULATOR_HOST を使用します。

MCP ツール (V1、読み取り専用)

接続: get_operator、list_microsoft_connections、get_microsoft_connection、start_microsoft_connection、disconnect_microsoft_connection

顧客 / アカウント: list_microsoft_customers、get_microsoft_customer、list_microsoft_accounts、get_microsoft_account

エンティティ: list_campaigns、get_campaign、list_ad_groups、get_ad_group、list_ads、get_ad、list_keywords、get_keyword

レポート (公式 Reporting API、非同期の送信/ポーリング/ダウンロード): get_account_performance、get_campaign_performance、get_ad_group_performance、get_keyword_performance

同じ広告アカウントが複数の Microsoft 接続を通じて表示できる場合、サーバーはあいまいさエラーを返し、connectionId を要求します。推測することはありません。

Firestore コレクション

名前付きデータベース: bing-mcp-v1

• bing_mcp_operators

• bing_mcp_microsoft_connections

• bing_mcp_connection_uniques ({operatorId}_{microsoftSubjectId})

• bing_mcp_microsoft_customers

• bing_mcp_microsoft_accounts

• bing_mcp_oauth_transactions

• bing_mcp_sessions

Cloud Run

Cloud Run のイングレスは未認証である必要があります。認証は MCP JWT であり、Cloud IAM ではありません。

Cloud Run サービスアカウントには、名前付きデータベースに対する Firestore アクセス権が必要です (通常は roles/datastore.user)。Application Default Credentials を使用します。サービスアカウントの JSON ファイルをコミットしないでください。

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-set-env.ps1 -ProjectId YOUR_PROJECT -AppBaseUrl https://... -MicrosoftClientId ... -MicrosoftClientSecret ... -McpTokenSecret ... -OauthStateSecret ... -TokenEncryptionKey ... -MicrosoftAdsDeveloperToken ...

次に、{APP_BASE_URL}/oauth/microsoft/callback を Entra アプリに追加し、{APP_BASE_URL}/mcp に Claude カスタムコネクタを追加します。非同期レポートを完了できるよう、サービス タイムアウトは 300 秒です。

セキュリティ

アクセストークン、更新トークン、クライアントシークレット、開発者トークン、暗号化キー、認可コードが、MCP やログを通じて公開されることは決してありません。

認可には operatorId + connectionId + Microsoft ID を使用します。名前と電子メールは認可識別子ではありません。

V2 (未実装)

キャンペーンの作成/更新/一時停止、広告グループと広告の書き込み、キーワードの書き込み、予算の更新。

テスト

npm test

自動テストは、MCP JWT の ID、Microsoft OAuth の state/交換/更新/invalid_grant、オペレーターの分離、複数接続、オペレーター間での同一 Microsoft ID、あいまいなアカウントの拒否、レポート CSV の解析、ヘッダールール、シークレットの秘匿化をカバーしています。

ライブの Claude、Microsoft ログイン、Cloud Run の各パスには、Entra アプリ、開発者トークン、GCP プロジェクトが必要です。