Skip to main content
Glama
aapl-ads-mcp

aapl-ads-mcp

by andrealufino

aapl-ads-mcp

Node version License andrealufino/aapl-ads-mcp MCP server

Claude(및 모든 MCP 호환 클라이언트)를 Apple Search Ads API v5에 연결하는 MCP 서버입니다.

소개

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 도구를 호출할 수 있도록 하는 개방형 표준입니다. 이 서버는 MCP stdio 전송을 구현하며, Apple Search Ads 계정(캠페인, 광고 그룹, 키워드 및 성과 보고서)을 쿼리할 수 있는 9개의 읽기 전용 도구를 제공합니다.

한 번 설치하고 Claude Desktop에 연결하면 다음과 같이 평문 영어로 질문할 수 있습니다: "지난달에 가장 많은 설치를 유도한 키워드는 무엇인가요?" 또는 "이번 주에 노출이 0인 캠페인을 보여줘."

Related MCP server: Reddit Ads MCP Server

목적

공식 ASA 대시보드는 사람에게는 유용하지만, 임시 분석이나 자동화된 보고에는 적합하지 않습니다. 기존의 MCP 대안들은 SaaS 방식(키를 넘겨줘야 함)이거나 유지 관리가 되지 않습니다. 이 프로젝트는 사용자가 직접 제어할 수 있는 오픈 소스 자체 호스팅 옵션입니다.

기능

  • list_orgs — 인증 확인 및 액세스 가능한 조직 목록 조회

  • list_campaigns — 캠페인 열거, 상태별 필터링 가능

  • list_ad_groups — 특정 캠페인의 광고 그룹 조회

  • list_keywords — 입찰가 및 일치 유형을 포함한 타겟팅 키워드 조회

  • get_campaign_report — 캠페인별 노출, 탭, 설치, 지출, CPI, TTR 조회

  • get_ad_group_report — 광고 그룹별 동일 지표 분석

  • get_keyword_report — 주간/일간/월간 단위의 키워드별 성과

  • get_search_terms_report — 광고를 트리거한 실제 검색어 조회 (발견에 가장 유용)

모든 도구는 기본적으로 지난 30일 데이터를 조회합니다. 보고서는 HOURLY, DAILY, WEEKLY, MONTHLY 단위를 지원합니다.

제한 사항

  • 설계상 읽기 전용. 이번 릴리스에서는 쓰기 작업(생성, 업데이트, 일시 중지)을 지원하지 않습니다.

  • Apple Search Ads 캠페인 관리 API 액세스 필요. ASA 계정에서 API 사용자를 생성하고 ES256 키 쌍을 생성해야 합니다.

  • 집계된 설치 지표는 앱 측 통합 없이 작동. ASA 보고서의 tapInstalls, viewInstalls 및 관련 필드는 Apple Search Ads에서 직접 채워지며 앱 내 SDK가 필요하지 않습니다. AdServices / AdAttributionKit은 앱 내부에서 특정 캠페인으로 설치를 기여시키려는 경우(예: 온보딩 개인화)에만 필요합니다.

  • 단일 조직. 조직 ID는 설정에 고정되어 있습니다. 다중 조직 전환은 구현되지 않았습니다.

설정

1. ES256 키 쌍 생성

최신 genpkey 명령을 사용하세요. 이 서버에서 요구하는 PKCS#8 형식을 직접 생성합니다. 이전의 ecparam -genkey는 SEC1 형식을 생성하여 시작 오류를 유발합니다.

# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem

# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pem

개인 키가 -----BEGIN PRIVATE KEY-----로 시작하는지 확인하세요(-----BEGIN EC PRIVATE KEY-----가 아님). EC 변형으로 시작하는 경우 변환하십시오:

openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem

가능하면 private-key.pem을 저장소 루트 외부(예: ~/.ssh/asa-private-key.pem)에 저장하세요.

2. Apple Search Ads에서 API 사용자 생성

  1. ASA → 계정 설정 → 사용자 관리로 이동

  2. 사용자 생성을 클릭하고, 읽기 전용 사용을 위해 API 계정 읽기 전용 역할을 선택합니다(이 서버에 권장). API 캠페인 관리자도 괜찮으며, 나중에 서버에 쓰기 도구를 추가할 계획이라면 쓰기 권한이 포함됩니다.

  3. API 탭으로 이동하여 클라이언트 생성을 클릭

  4. public-key.pem 업로드

  5. 확인 화면에서 client_id, team_id, key_id 복사

  6. 계정 설정 → 개요에서 org_id 확인

3. 복제 및 빌드

git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build

4. Claude Desktop 구성

~/Library/Application Support/Claude/claude_desktop_config.json을 편집하세요:

{
  "mcpServers": {
    "aapl-ads": {
      "command": "node",
      "args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",
"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"

} }


} }

참고: ASA_PRIVATE_KEY_PATH는 절대 경로여야 합니다. 물결표(~)는 Node.js에서 확장되지 않으므로 전체 경로를 사용하세요.

파일 마운트가 불가능한 컨테이너나 클라우드 배포의 경우, 대신 ASA_PRIVATE_KEY를 인라인 PEM 내용으로 설정하세요(줄 바꿈 유지). 둘 다 설정된 경우 ASA_PRIVATE_KEY가 우선합니다.

Claude Desktop을 다시 시작하세요. "run health check"라고 질문하여 서버가 연결되었는지 확인하세요.

사용 예시

서버가 실행 중일 때 Claude Desktop에서 작동하는 자연어 프롬프트입니다:


List my Apple Ads campaigns

지난 30일간의 캠페인 성과를 보여줘

지난주 내 브랜드 캠페인에서 설치를 유도한 키워드는 무엇인가요?

지난달에 내 광고를 트리거한 검색어는 무엇인가요? 노출은 있지만 설치가 없는 검색어에 집중해줘.

2025년 1분기 동안 모든 캠페인의 주간 지출을 비교해줘

캠페인 1234567890의 광고 그룹과 입찰가를 보여줘


## Development

```bash
npm run build      # compile TypeScript
npm test           # run test suite (Vitest)
npm run typecheck  # type-check without emitting
npm run lint       # Biome lint
npm run format     # Biome format (write)

MCP Inspector

Claude Desktop 없이 대화형으로 도구 호출을 디버깅하려면:

npx @modelcontextprotocol/inspector node dist/index.js

연결하기 전에 Inspector UI에서 환경 변수를 설정하세요.

Pre-commit 훅

복제 후 로컬에 lefthook 훅을 설치하세요:

npx lefthook install

다음이 설정됩니다:

  • gitleaks protect --staged — 비밀 정보가 포함된 커밋 차단

  • 스테이징된 .ts 파일에 대한 Biome 린트 검사

  • TypeScript 타입 검사

기여

기술적 세부 사항(인증 흐름, HTTP 클라이언트 설계, 도구 패턴, 보고서 스키마 특이 사항, 개발 중 배운 ASA v5 교훈)은 docs/ARCHITECTURE.md를 참조하세요.

버그 리포트와 풀 리퀘스트는 언제나 환영합니다.

보안

  • .env 또는 *.pem 파일을 절대 커밋하지 마세요(둘 다 .gitignore에 포함되어 있습니다)

  • private-key.pem을 저장소 루트 외부에 보관하세요

  • 액세스 토큰은 메모리에만 보관되며 디스크에 기록되지 않습니다

  • 키가 노출되었다고 의심되면 ASA → 계정 설정 → API에서 키를 교체하세요

라이선스

MIT — LICENSE 참조.

Available Tools

9 tools
get_ad_group_reportA

Fetch performance metrics for ad groups within a specific Apple Search Ads campaign: impressions, taps, TTR, spend, CPI, installs (tap-through and view-through), and install rate. Requires ASA authentication; read-only. Use get_campaign_report for a campaign-level summary, or get_keyword_report for keyword-level detail. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), endDate, startDate, adGroupIds, +1 more.

get_campaign_reportA

Fetch performance metrics for Apple Search Ads campaigns: impressions, taps, tap-through rate (TTR), localSpend, avgCPT, avgCPM, tapInstalls, viewInstalls, totalInstalls, new downloads, redownloads, CPI, and install rate. Requires ASA authentication; read-only. Use get_ad_group_report or get_keyword_report for deeper breakdowns. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: startDate, endDate, granularity, campaignIds.

get_keyword_reportA

Fetch performance metrics for targeting keywords in a specific Apple Search Ads ad group: impressions, taps, TTR, spend, CPI, installs, and install rate broken down per keyword. Requires ASA authentication; read-only. Use get_search_terms_report to see the actual user queries that triggered these keywords. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

get_search_terms_reportA

Fetch the actual user search queries that triggered Apple Search Ads impressions, along with performance metrics per search term. Requires ASA authentication; read-only. Most useful for keyword discovery (finding new terms to add) and negation (finding irrelevant queries to exclude). Does not support granularity breakdown — returns aggregate totals per search term. Use get_keyword_report to see metrics for your configured targeting keywords instead. Defaults to the last 30 days.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

healthA

Check if the aapl-ads-mcp server is running and reachable. Use this to verify the MCP connection before making API calls. No ASA authentication is required — returns server name, version, and current timestamp.

Inputs: no named parameters.

list_ad_groupsA

List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), limit, offset.

list_campaignsA

List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: status, limit, offset.

list_keywordsA

List targeting keywords for a specific Apple Search Ads ad group. Requires ASA authentication; read-only. Returns keyword metadata (text, match type BROAD/EXACT, bid amount, status) but not performance metrics — use get_keyword_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), adGroupId (required), limit, offset.

list_orgsA

List all Apple Search Ads organizations accessible with the configured credentials. Requires ASA authentication. Use this to verify credentials are valid and to discover available org IDs before calling other tools. Returns org ID, name, currency, timezone, payment model, and assigned role names.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action: list_* for enumerating hierarchy levels, get_*_report for metrics at each level, get_search_terms_report for search queries, and health for server status. No two tools could be confused for the same task.

    Naming Consistency4/5

    Most tools follow the list_ or get_*_report pattern clearly separating metadata enumeration from report retrieval. The single deviation is 'health', which is a noun rather than a verb-prefixed action (e.g., check_health), making the pattern slightly inconsistent.

    Tool Count5/5

    Nine tools is well-scoped for a read-only Apple Search Ads data access server: four list tools for entity hierarchy, four report tools for metrics breakdowns, and a health check. Each tool serves a distinct need without redundancy.

    Completeness4/5

    The read-only surface covers the full object hierarchy (org → campaign → ad group → keyword) with list operations and corresponding report endpoints, including search terms. However, the complete absence of write operations (no create/update/delete for campaigns or keywords) could be a gap if management tasks are expected, though it appears intentionally read-only.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.
      6
      72 PyPI
      46
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only analysis of Apple Ads Platform data, allowing AI assistants to query campaign structure, keywords, search terms, and performance reports without modifying anything.
      MIT