5분 만에 Apple Search Ads를 Claude 또는 ChatGPT에 연결하기

Hermoso Apple Search Ads 커넥터는 Apple Ads 계정을 Claude, ChatGPT, Cursor, CLI 또는 일반 HTTP에 연결하므로, 에이전트가 App Store 검색 광고를 대신 운영할 수 있습니다. 캠페인, 광고 그룹, 타기팅 키워드와 제외 키워드를 만들고, Apple이 실제로 저장한 내용을 다시 읽어 확인하며, 사용자가 설치 전에 입력한 검색어까지 내려가 성과를 보고합니다. 만들어지는 모든 항목은 일시중지 상태로 생성되며, 지출을 켜는 것은 명시적으로 확인받는 별도 단계입니다. 보고서는 Google 시트, Looker Studio 대시보드 또는 JSON 파일로 보낼 수 있고, Apple Ads MCP 페이지에서 커넥터가 할 수 있는 모든 작업을 볼 수 있습니다.

연결에는 약 5분이 걸립니다. openssl을 실행할 필요가 없고, Apple 비밀번호는 Hermoso 근처에 오지 않습니다.

Apple Search Ads를 Claude에 연결하기

Apple Search Ads를 Claude에 연결하려면 Claude에 Hermoso를 커넥터로 추가한 다음, Hermoso에서 Apple Ads 계정을 한 번 연결하면 됩니다. Claude에서 Customize › Connectors › Add custom connector를 열고, 이름을 Hermoso로 지정한 뒤 https://app.hermoso.ai/mcp를 붙여넣고 Hermoso 계정으로 승인합니다. Claude에 붙여넣을 키는 없습니다. 그다음 Hermoso의 설정 › 커넥터에서 이 페이지 아래의 단계에 따라 Apple Ads를 연결합니다. 그 이후 Claude는 Hermoso가 가진 Apple Ads 도구를 모두 호출할 수 있습니다. 보고서, 키워드 변경, 새 캠페인을 평범한 말로 요청하면 됩니다. Claude Code에서는 명령 두 개면 됩니다. /plugin marketplace add hermoso-ai/hermoso를 실행한 다음 /plugin install hermoso@hermoso를 실행합니다. Claude의 Hermoso에 전체 절차가 있습니다.

Apple Search Ads를 ChatGPT에 연결하기

ChatGPT도 같은 방식입니다. ChatGPT에서 Plugins를 열고 Add › Create MCP App을 선택한 다음, 이름을 Hermoso로 지정하고 Server URL에 https://app.hermoso.ai/mcp를 붙여넣습니다. Authentication은 OAuth로 두고 Hermoso 계정으로 승인하세요. Create MCP App이 보이지 않으면 Settings › Plugins › Developer mode를 한 번 켜세요. Hermoso에서 Apple Ads를 연결해 두면 ChatGPT가 키워드 보고서를 가져오거나, Google 시트에 기록하거나, 확인용 캠페인 초안을 작성할 수 있습니다. ChatGPT의 Hermoso에서 전 과정을 안내합니다.

Cursor, Codex 및 기타 MCP 클라이언트

Model Context Protocol을 지원하는 클라이언트라면 같은 주소에서 같은 도구에 접근할 수 있습니다. Cursor는 https://app.hermoso.ai/mcp를 mcp.json에서 읽습니다. Codex는 codex plugin marketplace add hermoso-ai/hermoso 명령으로 Hermoso 플러그인을 가져오며, 터미널에서 같은 도구를 실행합니다. 어떤 클라이언트를 쓰든 Apple 자격 증명은 채팅을 거치지 않습니다. 에이전트가 Hermoso의 도구를 호출하면, Hermoso가 보관 중인 키로 Apple에 보내는 각 요청에 서명합니다. Apple Ads MCP 페이지에서 모든 도구를 볼 수 있습니다.

연결한 뒤 물어볼 수 있는 것

• “지난주 Apple Search Ads 성과를 키워드별로 보여 주고, CPA가 가장 높은 10개를 알려 줘.”
• “최근 30일의 지출, 설치, CPA를 캠페인별로 정리해서 ‘Apple Ads’라는 새 Google 시트에 넣어 줘.” (먼저 Google Drive를 연결하세요.)
• “이번 달 미국 캠페인에서 설치를 가져온 검색어 중, 아직 정확 일치 키워드로 입찰하지 않는 것은 무엇인가?”
• “Brand 광고 그룹에 ‘budget planner’와 ‘expense tracker’를 정확 일치 키워드로 추가하고, ‘jobs’는 제외 키워드로 추가해 줘.”
• “Apple이 내 앱에 추천하는 키워드는 무엇이고, 이미 입찰 중인 키워드에서 내 노출 점유율은 얼마인가?”
• “영국에서 내 앱을 위한 일시중지 캠페인을 만들고 일일 예산을 50달러로 설정한 다음, Apple에 저장된 내용을 보여 줘.”

보고서를 읽어도 지출에는 아무 영향이 없습니다. 에이전트가 만드는 항목은 모두 일시중지 상태로 생성되며, 지출을 켜는 스위치는 사용자의 명시적 확인을 기다립니다.

먼저, 대부분을 멈추게 하는 것

Apple의 안내는 이렇습니다. “Ads UI에서 Account Settings › API를 선택합니다. 키를 Public Key 필드에 붙여넣습니다.”

계정 관리자에게는 그 필드가 없습니다. 자신의 계정에 관리자로 로그인해 Account Settings › API를 열면, Manage API Access라는 표(서드파티 서비스 제공업체 목록과 단일 Remove Access 작업)가 나타나고, 페이지 어디에도 키 입력란이 없습니다. 기능이 없는 것처럼 보이기 때문에 사람들이 여기서 멈추고, API를 쓸 수 없다고 결론짓습니다.

하지만 쓸 수 있습니다. Public Key 필드는 API 역할을 가진 사용자에게만 나타나며, 계정 관리자라는 지위는 API 역할이 아닙니다. Apple의 초대 대화상자에는 역할이 여섯 가지 있고, 그중 API 역할은 두 가지뿐입니다.

• API Account Manager: “API 관리를 위해 모든 캠페인 그룹에 대한 읽기 및 쓰기 권한”. Hermoso가 보고만이 아니라 캠페인을 만들기를 원한다면 이 역할을 고르세요.
• API Account Read Only: “API 관리를 위해 모든 캠페인 그룹에 대한 읽기 전용 권한”. 보고에는 충분하고, 그 밖에는 아무것도 할 수 없습니다.

나머지 네 가지(Account Admin, Account Finance, Account Read Only, Limited Access)는 API 자격 증명을 아예 만들 수 없습니다. 그래서 해결책은 자기 자신에게 보내는 초대입니다.

1. Account Settings › User Management를 열고 Invite Users를 고릅니다.
2. 직접 관리하는 주소(본인 주소, 또는 ads-api@yourcompany.com처럼 특정 한 사람보다 오래 가는 공용 주소)를 역할 API Account Manager로 초대합니다.
3. 그 받은편지함에서 초대를 수락한 다음, 그 사용자로 Apple Ads에 로그인합니다.

이제 Account Settings › API에 Public Key 필드가 나타납니다.

연결 단계별 안내

1. Hermoso에서 시작합니다. 설정 › 커넥터 › Apple Ads › Connect. Hermoso가 EC P-256 서명 키(prime256v1 키, Apple의 openssl 명령 두 개가 만들었을 것과 같은 키)를 생성하고 공개 키 반쪽만 보여 줍니다. 복사하세요.
2. 공개 키 반쪽을 Apple에 전달합니다. API 역할 사용자로 Account Settings › API를 열고, Public Key에 붙여넣은 뒤 Save를 누르세요.
3. ID 세 개를 다시 복사합니다. Apple이 이제 그 필드 위에 clientId, teamId, keyId를 표시합니다. 세 가지 모두 복사하세요.
4. Hermoso에서 마무리합니다. 세 ID를 붙여넣고 저장합니다. Hermoso는 아무것도 저장하기 전에 Apple과 토큰을 교환하고 조직 목록을 읽습니다. 그래서 잘못 입력한 ID는 그 자리에서 실패합니다. 한 시간 뒤 첫 보고서를 요청할 때가 아니라, 붙여넣은 내용이 아직 눈앞에 있을 때 드러납니다.
5. 조직을 고릅니다. 자격 증명이 둘 이상의 조직을 포함한다면 하나를 고르세요. 연결은 선택한 조직에 고정됩니다.

문제가 생겼을 때

API 페이지에 Public Key 필드가 없습니다

계정 관리자로 로그인했거나, API가 아닌 네 가지 역할 중 하나로 로그인한 상태입니다. 자신을 API Account Manager로 초대하고 그 사용자로 로그인하세요(위 내용 참고). 이것이 Apple Ads 연결이 만들어지지 않는 가장 흔한 이유입니다.

Apple이 자격 증명을 거부합니다

세 ID는 Apple이 보유한 키에 속해야 합니다. Public Key 필드 바로 위에서 clientId, teamId, keyId를 다시 복사하세요. 이전에 교체한 키에서 가져오면 안 됩니다. 그래도 실패하면 Hermoso에서 연결을 처음부터 다시 시작하세요. 그러면 새 키 쌍이 만들어지고, 새 공개 키 반쪽을 Apple에 붙여넣으면 됩니다.

설정 세션이 만료되었습니다

Hermoso는 생성한 비공개 키를 공개 키 반쪽을 Apple에 붙여넣을 때까지 24시간 동안 보관합니다. 그 이후에는 의도적으로 삭제됩니다. 연결을 다시 시작하고 새 공개 키를 붙여넣으세요.

openssl로 이미 키를 만들었습니다

그렇다면 그대로 쓰세요. 연결할 때 Hermoso의 키 대신 기존 EC P-256 비공개 키를 붙여넣으면, Apple 계정에 이미 있는 공개 키가 계속 작동합니다. EC P-256(prime256v1) 키여야 합니다. Apple은 다른 곡선을 받지 않습니다.

여러 Apple Ads 조직을 관리합니다

각 조직을 자신의 Hermoso 프로필에서 따로 연결하세요. 연결은 하나의 조직에 고정되며, 이것이 에이전시의 캠페인이 다른 고객의 계정에 잘못 들어가는 일을 막아 줍니다.

Apple Search Ads 커넥터가 할 수 있는 것

만들기: create_apple_ads_campaign, create_apple_ads_ad_group, add_apple_ads_keywords, add_apple_ads_negative_keywords, update_apple_ads_object, set_apple_ads_status, delete_apple_ads_object.

읽기: list_apple_ads_campaigns(상태, 서빙 상태, 일일 및 전체 예산, 캠페인이 실행되는 국가, 실행할 수 없을 때 Apple이 밝힌 이유), list_apple_ads_ad_groups(기본 입찰가, Search Match 사용 여부), list_apple_ads_keywords(매치 유형과 입찰가가 있는 타기팅 및 제외 키워드), apple_ads_report(캠페인, 광고 그룹, 광고, 키워드 또는 검색어 단위의 노출, 탭, 설치, 지출, TTR, CPT, CPA) 그리고 list_apple_ads_orgs.

이 모든 것은 Claude, Claude Code, Codex, Cursor, Cline, OpenClaw, Hermes 또는 다른 MCP 클라이언트에서, 그리고 웹 스튜디오에서 호출할 수 있습니다. 어느 쪽이든 같은 엔진입니다. MCP 개요 또는 광고 도구 레퍼런스를 보세요.

그 밖에도: 크리에이티브와 광고를 만들고(create_apple_ads_creative, create_apple_ads_ad), 한 번의 호출로 키워드를 최대 1,000개까지 넣고(bulk_apple_ads_keywords), Apple 자체 데이터를 읽습니다. apple_ads_keyword_suggestions, apple_ads_impression_share, apple_ads_search_term_popularity, apple_ads_change_history. 이 모든 도구는 같은 채팅에서 호출할 수 있습니다.

Apple Search Ads에서 데이터 내보내기

같은 연결로 보고서도 가져올 수 있습니다. apple_ads_report는 캠페인, 광고 그룹, 광고, 키워드, 검색어 단위의 성과(노출, 탭, 설치, 지출, 탭률, 탭당 비용, 설치당 비용)를 가져오며, 총합으로 받거나 시간별, 일별, 주별, 월별 시계열로 받을 수 있습니다. 페이지당 최대 5,000행입니다. 보고서를 읽어도 지출에는 영향이 없습니다. 데이터를 어디로 보낼지는 사용자가 정하며, 가장 흔한 세 가지 방법은 아래에 있습니다. 전체 가이드는 Apple Search Ads에서 데이터 내보내기를 보세요.

Apple Search Ads를 Google 시트에 연결하기

Google Drive를 Apple Ads 옆에 연결하고(Google 인증 하나로 Drive, Sheets, Docs가 모두 처리됩니다), 에이전트에게 보고서를 시트에 넣어 달라고 요청하세요. 에이전트는 apple_ads_report를 호출한 다음, 새 스프레드시트라면 create_sheet, 기존 시트에 이번 주 행을 추가하려면 append_to_sheet를 호출합니다. Hermoso는 Google의 drive.file 범위를 쓰므로, Hermoso가 만든 파일과 사용자가 고른 파일에만 접근합니다. 단계별 안내는 Apple Search Ads를 Google 시트에 연결하기에 있습니다.

Apple Search Ads를 Looker Studio로 내보내기

Hermoso에는 기본 Looker Studio 커넥터가 없습니다. Looker Studio는 자체 커넥터로 Google 시트를 읽으므로, 위의 시트가 다리 역할을 합니다. 시트를 Google Sheets 데이터 소스로 한 번 추가하고 대시보드를 만들면, 매주 추가되는 모든 행이 다음 새로고침 때 반영됩니다. Power BI와 Tableau도 같은 시트를 같은 방식으로 읽습니다. Looker Studio 단계를 보세요.

Apple Search Ads를 JSON으로 내보내기

원본 행이 필요하다면 API 키로 Hermoso REST API를 통해 도구를 호출하세요. POST https://app.hermoso.ai/v1/tools/apple_ads_report에 보고서 인수를 JSON 본문으로 보내고, 응답의 data.rows에서 행을 읽습니다. 터미널에서는 npx -y hermoso call apple_ads_report --json '{...}' --structured가 같은 결과를 JSON으로 출력합니다. 요청 예시 전체를 보세요.

자주 묻는 질문

Claude에 Apple Search Ads를 어떻게 연결하나요?

Hermoso를 https://app.hermoso.ai/mcp 주소의 사용자 지정 커넥터로 Claude에 추가하고 Hermoso 계정으로 승인한 다음, Hermoso의 설정 › 커넥터에서 Apple Ads를 연결하세요. 그러면 Claude가 Hermoso의 Apple Ads 도구로 Apple Search Ads 캠페인을 보고, 편집하고, 만들 수 있습니다.

ChatGPT가 내 Apple Search Ads 데이터를 읽을 수 있나요?

네. ChatGPT에서 Plugins › Add › Create MCP App으로 https://app.hermoso.ai/mcp를 추가하고, Hermoso에서 Apple Ads를 연결하세요. 그러면 ChatGPT가 캠페인, 광고 그룹, 광고, 키워드 또는 검색어별로 노출, 탭, 설치, 지출, TTR, CPT, CPA를 가져와 행을 Google 시트에 기록할 수 있습니다.

Apple Search Ads MCP 서버가 있나요?

있습니다. https://app.hermoso.ai/mcp의 호스팅 MCP 서버가 Claude, ChatGPT, Cursor, Codex 또는 다른 MCP 클라이언트에 Apple Ads 도구 전체를 제공합니다. 보고, 캠페인, 광고 그룹, 키워드와 제외 키워드, 크리에이티브와 광고, Apple의 키워드 추천이 모두 포함됩니다. 만들어지는 모든 항목은 일시중지 상태입니다.

Apple Ads API 페이지에 Public Key 필드가 없는 이유는 무엇인가요?

계정 관리자로 로그인했기 때문입니다. Apple은 API 역할을 가진 사용자에게만 그 필드를 보여 줍니다. 관리자에게는 대신 “Manage API Access” 표, 즉 서드파티 서비스 제공업체 목록이 보이며, 페이지 어디에도 키 필드가 없습니다. Account Settings › User Management에서 자신을 API Account Manager로 초대하고 그 사용자로 로그인하면 필드가 나타납니다.

어떤 Apple Ads 역할이 필요한가요?

Hermoso가 캠페인, 광고 그룹, 키워드를 만들기를 원한다면 API Account Manager입니다. Apple은 이를 “API 관리를 위해 모든 캠페인 그룹에 대한 읽기 및 쓰기 권한”이라고 설명합니다. 보고만 필요하다면 API Account Read Only로 충분합니다. Apple이 제공하는 나머지 네 가지 역할(Account Admin, Account Finance, Account Read Only, Limited Access)은 API 자격 증명을 전혀 만들 수 없습니다.

openssl을 실행해야 하나요?

아니요. Apple의 안내는 openssl 명령 두 개를 주지만, Hermoso가 EC P-256 키 쌍을 생성하고 공개 키 반쪽만 보여 줍니다. 요청에 서명하는 비공개 키 반쪽은 보거나, 붙여넣거나, 저장할 필요가 없습니다. 다른 도구로 만든 키가 이미 있다면 그것을 가져와도 됩니다.

Apple Ads를 연결하는 데 비용이 들거나 지출 위험이 있나요?

아니요. 읽기 호출은 비용이 없고, Hermoso가 만드는 모든 항목은 예외 없이 PAUSED 상태로 생성됩니다. 항목을 활성화하는 것만이 실제 지출을 켜며, 이는 명시적 확인이 필요합니다.

clientId, teamId, keyId는 무엇인가요?

키를 저장하면 Apple이 Public Key 필드 위에 표시하는 세 가지 식별자입니다. API 사용자를 Apple에 식별해 주고, 비공개 키가 본인임을 증명합니다. 세 가지를 Hermoso에 다시 붙여넣으면 연결이 끝납니다.

하나의 연결로 여러 Apple Ads 조직을 다룰 수 있나요?

하나의 연결은 만들 때 고른 조직 하나에 고정됩니다. Apple은 orgId를 캠페인 그룹과 비슷하게 취급하므로, 한 로그인으로 여러 조직을 포함할 수는 있습니다. 조직마다 고객이 있는 에이전시는 각 조직을 자신의 Hermoso 프로필에서 따로 연결합니다.

180일마다 키를 교체해야 하나요?

아니요. Apple은 클라이언트 시크릿의 수명을 180일로 제한하므로 Apple의 안내가 교체 일정을 적어 두라고 하는 것입니다. Hermoso는 비공개 키를 보관하고 토큰을 교환할 때마다 새 짧은 수명의 시크릿을 만들므로, 만료될 것이 설정 파일에 남아 있지 않습니다.

Apple Search Ads 데이터를 Google 시트나 Looker Studio로 내보낼 수 있나요?

네. Apple Ads 옆에 Google Drive를 연결하면 에이전트가 create_sheet 또는 append_to_sheet로 보고서를 Google 시트에 씁니다. Hermoso에는 기본 Looker Studio 커넥터가 없으며, Looker Studio는 자체 Google 시트 커넥터로 그 시트를 읽습니다.

Apple Search Ads 데이터를 JSON으로 받을 수 있나요?

네. API 키로 Hermoso API의 POST /v1/tools/apple_ads_report를 호출하고 응답의 data.rows를 읽거나, CLI에서 --structured와 함께 hermoso call apple_ads_report를 실행하세요.