Apple Ads MCP

로컬 우선 Model Context Protocol 서버로, Apple Ads Platform API v1용입니다. Codex, Claude 및 기타 MCP 클라이언트에 App Store 광고 조사, 보고, 감사, 영수증 기반 캠페인 관리를 위한 타입화된 도구를 제공합니다.

Apple Ads MCP는 독립적인 오픈소스 소프트웨어입니다. Apple Inc.와 제휴하거나 보증하거나 후원하지 않습니다. Apple Ads 및 App Store는 Apple Inc.의 상표입니다.

Apple Ads MCP를 선택하는 이유

• 에이전트 우선 도구: 소유한 앱 검색, 키워드 조사, 보고서 검토, 캠페인 감사, 좁은 범위의 변경 준비.

• 로컬 자격 증명: 개인 키는 사용자 머신에 유지됩니다. OAuth 토큰과 운영 영수증은 프로세스 메모리에만 유지됩니다.

• 기본적으로 읽기 전용: 조사와 보고는 변경을 활성화하지 않고도 작동합니다.

• 명시적 계정 라우팅: 모든 계정 범위 도구는 프로필과 adAccountId가 필요합니다.

• 안전한 변경: 모든 쓰기 작업에는 미리 보기, 10분 단일 사용 영수증, 현재 상태 재확인이 필요합니다.

• 제한된 출력: 구조화된 MCP 콘텐츠, 제한된 배열, 페이지네이션, 속도 제한 메타데이터, 구조화된 Apple 오류.

• 휴대용 런타임: macOS, Linux, Windows용 단일 Go 바이너리와 OCI 이미지.

Related MCP server: OpenAI Ads MCP

릴리스 상태

v0.1.0은 첫 공개 릴리스입니다. 전체 로컬 테스트 스위트, 레이스 감지기, 정적 분석, 취약점 스캔, 비밀 스캔, 배포 검증, 실제 MCP stdio 테스트가 모두 통과합니다.

운영자가 제어하는 Apple Ads 계정에 대한 비공개 라이브 수락 테스트에서 다음을 검증했습니다:

• OAuth, 계정 검색, 조직 및 소유 앱 조회;

• 스토어프론트 가용성, 키워드 제안, 인기 인사이트, 제한된 보고서;

• 미리 보기 → 영수증 → 적용 → 직접 API 읽기;

• 일시중지된 캠페인, 광고 그룹, 타겟 키워드, 부정 키워드 생성;

• 드리프트 거부, 단일 사용 영수증, 읽기 전용 복원, 광고 지출 0.

이 저장소에는 자격 증명, 계정 내보내기, 비공개 캠페인 데이터 또는 라이브 영수증이 저장되지 않습니다.

기능

읽기 도구

영수증 기반 쓰기 도구

• 캠페인, 광고 그룹, 타겟 키워드, 부정 키워드 생성 및 업데이트.

• 광고 및 App Store 크리에이티브에 대한 공급별 미리 보기 기반 사용; 지원은 여전히 Apple 배치 및 제품 페이지 조합에 따라 다릅니다.

• 캠페인 일시중지/재개, 광고 그룹 입찰가, CPA 상한 미리 보기.

• operations_apply를 통해 정확히 하나의 미리 보기를 적용.

• operations_inspect 및 operations_verify를 통해 모호한 작업을 검사하거나 검증.

일반적인 원시 요청 도구는 없습니다. Apple Maps, 레거시 Campaign Management API v5, 자동 예산 증가, 파괴적 삭제, 권장 사항 적용/해제 작업은 의도적으로 제외됩니다.

안전 모델

변경은 다음 조건이 모두 충족될 때만 가능합니다:

1. Apple 사용자가 명시적 광고 계정에 대해 인식된 API 쓰기 역할을 가집니다.

2. 서버가 --allow-writes로 시작합니다.

3. 선택한 프로필에 allowWrites: true가 있습니다.

4. 전용 *_preview 도구가 영수증을 반환합니다.

5. operations_apply가 동일한 만료되지 않은 영수증을 받습니다.

6. 현재 Apple 리소스가 미리 보기 중 읽은 상태와 여전히 일치합니다.

영수증은 10분 후 만료되며 단일 사용입니다. 모호한 전송 실패 후 변경이 재시도되지 않습니다. 서버는 committed_unverified를 반환하고 후속 쓰기 전에 직접 상태 확인이 필요합니다.

일반적인 조사 및 보고의 경우 --allow-writes 없이 서버를 실행하고 모든 프로필을 allowWrites: false로 유지하세요.

설치

GitHub 릴리스

GitHub Releases에서 플랫폼용 아카이브를 다운로드하세요. 각 릴리스에는 SHA-256 체크섬과 SPDX SBOM이 포함됩니다.

Apple 실리콘 예시:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Homebrew 포뮬러

릴리스는 체크섬 고정 포뮬러를 자산으로 게시합니다:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp.rb
brew install --formula ./apple-ads-mcp.rb

OCI 이미지

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.1.0

이미지는 기본적으로 serve --stdio로 실행됩니다. accounts.json과 참조된 개인 키를 읽기 전용으로 마운트하세요. 키가 소유자 전용인 경우 해당 호스트 UID/GID로 컨테이너를 실행하세요.

소스에서 빌드

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./bin/apple-ads-mcp ./cmd/apple-ads-mcp

Go 1.26.6 이상이 필요합니다.

Apple Ads API 설정

Apple Ads API 액세스는 App Store Connect 액세스와 별개입니다. Apple Ads 계정 관리자가 적절한 역할을 가진 API 사용자를 추가해야 합니다. 캠페인 변경이 필요할 때까지 API Account Read Only를 선호하세요.

로컬에서 ES256 키 쌍을 생성하세요:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

Apple Ads에 공개 키만 업로드하세요. 개인 키는 저장소 외부에 보관하고 에이전트 대화, 이슈 또는 로그에 절대 붙여넣지 마세요.

Apple이 공개 키를 등록한 후 Apple Ads UI에 표시된 비밀 아닌 클라이언트 ID, 팀 ID, 키 ID를 기록하세요.

구성

대화형으로 프로필 생성:

apple-ads-mcp config init

기본 구성 경로:

~/.config/apple-ads-mcp/accounts.json

동등한 JSON:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false
    }
  ]
}

POSIX 시스템에서 두 파일 모두 소유자 전용이어야 합니다:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

구성에는 프로필 메타데이터와 개인 키 경로만 저장됩니다. 개인 키를 포함하지 않습니다.

인증을 검증하고 액세스 가능한 계정을 검색하세요:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

구성 우선 순위:

1. --config

2. APPLE_ADS_MCP_CONFIG

3. ~/.config/apple-ads-mcp/accounts.json

4. 단일 프로필 APPLE_ADS_* 환경 변수

지원되는 환경 변수는 APPLE_ADS_PROFILE, APPLE_ADS_CLIENT_ID, APPLE_ADS_TEAM_ID, APPLE_ADS_KEY_ID, APPLE_ADS_PRIVATE_KEY_PATH, APPLE_ADS_AD_ACCOUNT_ID, APPLE_ADS_ALLOW_WRITES입니다.

MCP 클라이언트 연결

stdio로 서버 시작:

apple-ads-mcp serve --stdio

Codex, Claude Desktop 또는 다른 stdio 클라이언트용 일반 MCP 구성:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Claude Code:

claude mcp add apple-ads -- apple-ads-mcp serve --stdio

릴리스 아카이브에는 Codex 플러그인 메타데이터와 apple-ads-operator 스킬도 포함되어 있습니다. 이 스킬은 프롬프트에 자격 증명을 넣지 않고 온보딩, 조사, 캠페인 워크플로, 변경 안전을 라우팅합니다.

한 세션에 대해 쓰기 활성화

가능하면 영구 프로필에서 allowWrites: false를 유지하세요. 명시적으로 승인된 유지 관리 세션의 경우 두 게이트를 일시적으로 활성화하세요:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

Apple ACL, 명시적 profile, 명시적 adAccountId, 미리 보기, 영수증 바인딩, 만료, 드리프트 검사는 여전히 적용됩니다. 쓰기 게이트로 서버를 시작해도 자체적으로는 아무것도 변경되지 않습니다.

알려진 플랫폼 동작

• Apple Ads에는 공개 샌드박스가 없습니다. 자동화된 라이브 CI는 선택 사항이며 엄격히 읽기 전용입니다.

• 가용성, 제안, 인기, 권장 사항, 보고서는 계정, 앱, 스토어프론트, 캠페인 기록에 따라 다릅니다.

• 콜드 계정은 타겟 CPA 또는 예산 권장 사항을 반환하지 않을 수 있습니다.

• Apple은 엔드포인트별 검증 또는 서버 오류를 반환할 수 있습니다. MCP는 4xx 응답에 대해 제한된 안전 세부 정보를 보존하고 재시도 가능한 서버 오류는 편집합니다.

• 라이브 수락 테스트 중 Apple은 APPSTORE_SEARCH_RESULTS 공급 소스에 대해 별도의 Ad 객체를 거부했습니다. 검색 결과는 앱의 게시된 기본 제품 페이지를 사용했습니다.

• 캠페인 이름은 Apple에서 검증합니다. 웹 UI에서 허용되는 일부 구두점은 API에서 거부될 수 있습니다.

• 성과 보고서는 전달 데이터가 존재할 때까지 비어 있습니다. 설치에서 구독 또는 평가판으로의 기여는 이 API가 아닌 기여 스택에 속합니다.

• 전체 업스트림 MCP 적합성 러너 적용 범위는 현재 러너가 서버 URL을 수락하지만 stdio 자식 프로세스를 시작할 수 없기 때문에 보류 중입니다. 이 저장소는 공식 Go SDK를 통해 실제 stdio 세션을 테스트합니다.

개발

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py

라이브 테스트는 명시적 로컬 자격 증명이 필요하며 자동으로 변경을 실행하지 않습니다. CONTRIBUTING.md, SECURITY.md, 로드맵, 기계 판독 가능한 운영 매트릭스를 참조하세요.

릴리스 아티팩트

모든 태그된 릴리스는 다음을 게시합니다:

• 지원되는 경우 AMD64 및 ARM64용 macOS, Linux, Windows 아카이브;

• SHA-256 다이제스트가 포함된 checksums.txt;

• Syft로 생성된 SPDX 소프트웨어 자재 명세서;

• 체크섬 고정 Homebrew 포뮬러;

• Linux AMD64 및 ARM64용 다중 아키텍처 OCI 이미지;

• MCP 레지스트리 패키지 메타데이터.

라이선스

MIT