mcp-microsoft-ads

비공식 — Microsoft와 제휴, 보증, 또는 지원되지 않음. 이는 Microsoft Advertising용 타사 MCP(Model Context Protocol) 서버입니다. "MCP"는 AI 어시스턴트(Claude 또는 다른 MCP 클라이언트)가 실제 시스템 — 여기서는 귀하의 Microsoft Ads 계정 — 에 대해 도구를 호출할 수 있게 하는 개방형 프로토콜입니다.

안전 우선 Microsoft Ads MCP: 캠페인, 광고 그룹, 키워드, 부정 키워드, 지역 타겟팅, 광고 일정, 확장, 미디어, 오디언스, 전환 목표 관리와 성과 보고 및 Ad Insight 키워드 연구를 다루는 47개 도구 — AI 어시스턴트에게 라이브 광고 계정에 대한 쓰기 액세스를 부여하는 것이 무제한 수표를 주는 것을 의미하지 않도록 설계되었습니다.

"안전 우선"의 이유

모든 변경 도구는 기본적으로 꺼져 있습니다. 쓰기를 켜는 것은 환경 변수 하나이며, 그 경우에도 모든 쓰기는 Microsoft API에 단일 호출이 도달하기 전에 동일한 계층형 게이트를 거칩니다:

1. MS_ADS_ENABLE_WRITES=true — 이 값이 없으면 모든 쓰기 도구는 실행을 거부합니다. 기본적으로 이 서버는 읽기 전용입니다.

2. 초안 → 확인. 쓰기 도구는 자체 호출에서 변경하지 않습니다. 미리보기(draft_id 및 정확히 무엇이 변경될지)를 반환합니다. 귀하 또는 귀하의 MCP 클라이언트가 confirm_and_apply(draft_id)를 호출할 때까지 아무것도 적용되지 않습니다.

3. 지출 상한. 초안 생성과 적용 모두 MS_ADS_MAX_DAILY_BUDGET(기본값 1000) 또는 MS_ADS_MAX_CPC(기본값 50)를 초과하는 금액을 거부합니다. 계정 자체 통화로, USD가 아닙니다.

4. 스마트 입찰 실패 시 차단 가드. 입찰/조정 쓰기는 수동 입찰 전략(ManualCpc, EnhancedCpc, ManualCpv, ManualCpm, ManualCpa)으로 허용 목록에 등록됩니다. 인식되지 않거나 자동화된 전략(MaxConversions, TargetCpa, TargetRoas, …)은 안전하다고 가정하지 않고 거부됩니다.

5. JSONL 감사 로그. 모든 초안과 모든 적용은 로컬의 추가 전용 JSONL 파일에 추가됩니다 — 이 서버가 실제로 수행한 작업에 대한 일반 텍스트 기록입니다.

380개 이상의 오프라인 테스트(라이브 API 호출 없음)로 뒷받침되며, 레일, SOAP 파이프라인 특이점, 초안/확인 수명 주기를 페이크에 대해 테스트합니다.

"초안 → 확인"이 아닌 것에 대해 솔직하게

초안 → 확인은 단일 호출 사고에 대한 미리보기 게이트입니다 — 입찰의 오타, 복사-붙여넣기 실수, 잘못된 도구 호출. 인간 승인 액세스 제어가 아닙니다: 초안을 만든 동일한 MCP 클라이언트가 즉시 confirm_and_apply를 호출할 수 있으며, 서버가 요구하는 인간 개입이 없습니다. 모든 쓰기를 인간이 검토하도록 하려면 자체 워크플로(별도 승인 단계, 인간 전용 클라이언트 등)로 강제해야 합니다 — 이 서버는 그렇게 하지 않습니다.

하나의 쓰기는 계층형 스토리가 완전히 제한할 수 없기 때문에 별도로 언급됩니다: **apply_recommendation**은 Microsoft가 결정한 변경에 위임합니다 — 권장 ID만 미리보고 변경 자체는 미리보지 않으므로 실제 금전적 영향은 이 서버의 지출 상한이 사전에 확인할 수 없습니다. 이 도구는 유지되며(Microsoft의 권장 사항이 유용할 수 있음), 예외임을 크게 표시하고, **MS_ADS_ENABLE_WRITES**와 별도의 플래그 MS_ADS_ALLOW_APPLY_RECOMMENDATION 둘 다 뒤에 게이트됩니다 — 일반적으로 쓰기를 켜도 이 도구는 켜지지 않습니다.

이 서버가 하지 않는 것

• 품질 점수 진단 없음.

• 일시적인 API 실패에 대한 자동 재시도/백오프 없음(실패한 호출은 실패; 직접 재시도).

• Microsoft가 수명 종료를 발표한 SOAP Bing Ads SDK 기반 — 아래 참조.

Related MCP server: OpenAI Ads MCP

SOAP 수명 종료 및 REST 로드맵

이 서버는 bingads SOAP SDK를 기반으로 합니다. Microsoft는 SOAP가 2027-01-31에 수명 종료될 것이라고 발표했으며, 2026-10-01 이전에 마이그레이션할 것을 권장합니다(그 이후에는 새 API 기능이 REST 전용으로 제공됨). Microsoft의 REST API로 마이그레이션 가이드 및 Python SDK SOAP-to-REST 마이그레이션 가이드를 참조하세요. 이 서버의 도구를 REST로 포팅하는 것이 로드맵 항목입니다 — SOAP는 오늘날에도 작동하며 EOL 날짜까지 사라지지 않지만, 장기적으로 계획하지 마세요.

비교

비교는 2026-08-24에 마지막으로 확인되었습니다. 이 프로젝트는 다른 행의 정확한 현재 기능 세트를 읽기 전용 여부 외에는 알지 못한다고 주장합니다 — 각 프로젝트의 저장소/문서에서 세부 사항을 확인하세요. 위의 차별점(선택적 쓰기, 2단계 초안→확인, 지출 상한, 스마트 입찰 실패 시 차단 가드, JSONL 감사 로그, 380개 이상의 오프라인 테스트)이 이 프로젝트가 구축된 핵심입니다.

설치

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]"

전체 설정 — Azure 앱 등록, 개발자 토큰, 첫 OAuth 로그인 — 은 docs/setup.md에 있습니다. 이 섹션은 자격 증명이 이미 존재하는 경우 서버 실행만 다룹니다.

자격 증명

자격 증명은 저장소 외부의 YAML 파일(기본 ~/.mcp-microsoft-ads/credentials.yaml, MS_ADS_CREDENTIALS_PATH로 재정의)에 있습니다: developer_token, client_id, client_secret, refresh_token, customer_id, account_id, tenant.

여섯 개의 정적 필드(refresh_token 제외)는 대신 MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET, MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT 환경 변수로 설정할 수 있습니다 — 둘 다 있을 때 환경 변수가 파일보다 우선합니다. refresh_token은 파일 전용입니다: Microsoft는 사용할 때마다 회전시키며, 회전된 토큰은 다음 실행을 위해 어딘가에 저장되어야 하는데 환경 변수로는 불가능합니다. 서버는 각 회전을 자격 증명 파일에 원자적으로 다시 저장합니다(.bak이 유지됨).

첫 실행 안내

1. 부트스트랩 로그인:

   .venv/bin/python -m mcp_microsoft_ads.reauth

   브라우저에서 대화형 OAuth 로그인을 진행하고 결과 refresh_token을 자격 증명 파일에 씁니다. 이 단계가 의존하는 Azure 앱 등록 및 개발자 토큰은 docs/setup.md를 참조하세요.

2. 서버를 읽기 전용으로 시작하고(MS_ADS_ENABLE_WRITES를 아직 설정하지 마세요) MCP 클라이언트에서 health_check를 호출한 다음 list_accounts 및/또는 get_account_info를 호출하세요.

3. 계정이 의도한 계정인지 확인 — 해당 호출에서 반환된 계정 ID, 계정 이름, 계정 통화를 이 서버가 접근하도록 허용하려는 계정과 비교하세요. 아래 지출 상한은 해당 계정의 통화로 적용되므로 통화 불일치는 쓰기가 켜지기 전에 잡아내는 것이 좋습니다.

4. 그런 다음에만 MS_ADS_ENABLE_WRITES=true(및 원한다면 MS_ADS_ALLOW_APPLY_RECOMMENDATION=true)를 설정하고 서버를 다시 시작하세요.

MCP 클라이언트 구성

두 구성 모두 위의 venv가 ~/mcp-microsoft-ads/.venv에 있다고 가정합니다 — 실제 머신의 절대 경로로 바꾸세요(두 클라이언트 모두 ~가 아닌 절대 경로가 필요합니다).

Claude Code (프로젝트의 .mcp.json 또는 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"]
    }
  }
}

동시 클라이언트 두 개를 동일한 자격 증명 파일에 연결하지 마세요

동시 클라이언트 간에 하나의 자격 증명 파일을 공유하는 것은 지원되지 않습니다. refresh_token은 회전하는 공유 변경 가능 파일입니다: 모든 새로 고침은 새 토큰을 생성하고 이전 토큰을 즉시 무효화하며, 회전을 유지하는 읽기-수정-쓰기는 이 계층에서 두 개의 별도 프로세스 간에 안전하게 직렬화할 수 없습니다. 동일한 파일에서 새로 고침을 경쟁하는 두 클라이언트는 무효화된 토큰으로 서로를 좌초시킬 수 있습니다. 둘 이상의 동시 클라이언트(예: Claude Code와 Claude Desktop을 동시에 열어 두는 경우)를 원한다면 각각에 자체 자격 증명 파일과 자체 Azure 앱 등록을 제공하세요 — 클라이언트마다 MS_ADS_CREDENTIALS_PATH를 다르게 설정하고 각각 자체 reauth 실행으로 부트스트랩하세요.

환경 변수

통화 참고: MS_ADS_MAX_DAILY_BUDGET 및 MS_ADS_MAX_CPC는 USD로 변환하지 않고 계정 자체 통화의 금액과 직접 비교됩니다. 1000 상한선은 계정이 사용하는 통화의 1000단위를 의미합니다.

테스트 / 린트

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

문서

• docs/setup.md — Azure 앱 등록, 개발자 토큰, 전체 부트스트랩.

• SECURITY.md — 취약점 신고 방법.

• CHANGELOG.md — 릴리스 기록.

라이선스 및 지원

MIT 라이선스 — LICENSE 참조. 이 프로젝트는 최선을 다하는 무급 오픈소스 프로젝트입니다: SLA 없음, 응답 시간 보장 없음. 이슈는 최선을 다해 모니터링하고 분류합니다.