Microsoft Advertising MCP Connector

Claude.ai 사용자 지정 커넥터용 독립형 True Model B MCP 서버입니다. 한 명의 운영자는 여러 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의 mcp-handler 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 개발자 설정에서 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 인그레스는 인증되지 않은 요청을 허용해야 합니다. 인증은 Cloud IAM이 아닌 MCP JWT입니다.

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 ...

그런 다음 Entra 앱에 {APP_BASE_URL}/oauth/microsoft/callback을 추가하고 {APP_BASE_URL}/mcp에 Claude 사용자 지정 커넥터를 추가하세요.

비동기 보고서가 완료될 수 있도록 서비스 제한 시간은 300초입니다.

보안

MCP나 로그를 통해 절대 노출되지 않음: 액세스 토큰, 새로 고침 토큰, 클라이언트 비밀, 개발자 토큰, 암호화 키, 인증 코드.

권한 부여는 operatorId + connectionId + Microsoft ID를 사용합니다. 이름과 이메일은 권한 부여 식별자가 아닙니다.

V2(구현되지 않음)

캠페인 생성/업데이트/일시중지, 광고 그룹 및 광고 쓰기, 키워드 쓰기, 예산 업데이트.

테스트

npm test

자동화된 테스트는 MCP JWT ID, Microsoft OAuth 상태/교환/새로 고침/invalid_grant, 운영자 격리, 다중 연결, 운영자 간 동일한 Microsoft ID, 모호한 계정 거부, 보고서 CSV 파싱, 헤더 규칙 및 비밀 편집을 다룹니다.

라이브 Claude, Microsoft 로그인 및 Cloud Run 경로에는 Entra 앱, 개발자 토큰, GCP 프로젝트가 필요합니다.