Mağaza MCP란 무엇인가요?
Mağaza MCP는 한 번의 설치로 AI 어시스턴트가 App Store Connect와 Google Play 모두에 액세스할 수 있도록 하는 오픈 소스 Model Context Protocol 서버입니다. 별도의 통합 기능 사이를 전환하지 않고 iOS 및 Android 스토어 데이터를 확인하고, 비교하고, 관리해야 하는 개발자와 앱 운영자를 위해 설계되었습니다.
이 서버는 사용자의 컴퓨터에서 로컬로 실행되며 Apple 및 Google과 직접 통신합니다. 중개 서비스는 없습니다. Apple 도구는 appstore__ 접두사를 사용하고, Google Play 도구는 play__를 사용하며, 여러 스토어 또는 일반 API 도구는 magaza__를 사용합니다.
Mağaza MCP의 차별화된 기능은 여러 스토어에 걸친 질문에 한 번의 작업으로 답할 수 있다는 점입니다. 예를 들어 어시스턴트가 App Store와 Google Play에서 동일한 구독의 터키 가격을 비교하거나, 서로 대응하는 iOS 및 Android 애플리케이션을 연결하거나, 두 스토어에서 구매 구성 문제를 조사할 수 있습니다.
주요 기능
- 두 스토어를 위한 하나의 MCP 서버: App Store Connect, Google Play 또는 두 스토어 모두에 연결합니다.
- 스토어 간 워크플로: 구독을 비교하고, 통합 애플리케이션 개요를 생성하며, 두 플랫폼의 인앱 구매 구성을 진단합니다.
- 27개의 전문 도구: 두 스토어를 모두 사용하는 설치에서는 일반적인 스토어 작업과 일반 API 액세스를 위한 27개의 도구가 제공됩니다.
- 전체 API 범위: App Store Connect API v4.5, Android Publisher API v3, Play Developer Reporting API v1beta1에서 1,440개의 작업을 검색하고 호출합니다.
- 낮은 컨텍스트 오버헤드: 전체 API 카탈로그는 1,440개의 작업을 각각 별도의 MCP 도구로 노출하는 대신 검색 및 디스패치 도구를 통해 액세스합니다.
- 로컬 자격 증명 저장: 사용 가능한 경우 자격 증명을 macOS Keychain에 보관하며, Keychain을 사용할 수 없는 시스템에서는 권한이 제한된 파일을 대체 수단으로 사용합니다.
- 쓰기 작업 확인: 데이터를 변경하는 작업에는 명시적인
onayla=true확인이 필요합니다. - 읽기 전용 모드: 모델의 도구 목록에서 쓰기 도구를 완전히 제거할 수 있습니다.
- 텔레메트리 없음: 프로젝트는 분석 데이터, 오류 보고서 또는 사용 데이터를 전송하지 않습니다.
사전 요구 사항
패키지를 실행하기 전에 Node.js 18 이상을 설치하세요. 연결하려는 각 스토어에 적합한 자격 증명도 필요합니다.
App Store Connect 요구 사항
App Store Connect API 키를 생성하고 설정 중에 사용할 Key ID, Issuer ID 및 .p8 파일을 준비하세요. 대부분의 작업에는 App Manager 역할이면 충분합니다. 사용자 및 액세스 관리 엔드포인트와 일부 분석 보고서에는 더 높은 권한이 필요할 수 있습니다.
키는 App Store Connect API 키여야 합니다. StoreKit 키와 푸시 알림 키는 대체 수단으로 사용할 수 없습니다.
Google Play 요구 사항
- Play Console → Users and permissions를 통해 서비스 계정을 초대한 다음 관련 애플리케이션에 대한 액세스 권한을 부여합니다.
- 연결된 Google Cloud 프로젝트에서 Android Publisher API와 Play Developer Reporting API를 모두 사용 설정합니다.
Reporting API는 비정상 종료 지표뿐 아니라 애플리케이션 검색에도 필요합니다. Android Publisher API에는 계정에서 사용할 수 있는 모든 애플리케이션을 나열하는 엔드포인트가 없습니다.
이러한 API를 통해 계약, 세금 정보 및 은행 정보를 읽을 수는 없습니다. Apple은 App Store Connect API 키를 통해 해당 정보를 공개하지 않습니다.
Mağaza MCP 설치
다음 한 줄 명령으로 대화형 설치 프로그램을 시작합니다.
npx magaza-mcp kur마법사가 다음 단계를 안내합니다.
- App Store Connect, Google Play 또는 두 스토어를 모두 선택합니다.
- App Store Connect Key ID와 Issuer ID를 입력한 다음
.p8파일의 경로를 제공합니다. - Google Play 서비스 계정 JSON 파일의 경로를 제공합니다.
- MCP 구성을 설치할 검색된 AI 클라이언트를 선택합니다.
- 서버를 읽기 전용 모드로 운영할지 선택합니다.
설치 프로그램은 자격 증명을 저장하기 전에 실제 API 요청으로 Apple 및 Google 자격 증명을 검증합니다. 자격 증명은 AI 클라이언트의 구성 파일에 기록되지 않습니다. 구성에는 MAGAZALAR를 통해 어떤 스토어가 활성화되어 있는지와 같은 정보만 포함됩니다.
macOS에서는 자격 증명이 Keychain에 저장됩니다. Keychain을 사용할 수 없는 경우 프로젝트는 권한이 0600으로 설정된 파일을 사용합니다.
지원되는 MCP 클라이언트
설치 프로그램은 Claude Code, Claude Desktop, Antigravity, Cursor, Windsurf 및 Codex를 지원합니다. magaza-mcp 항목만 업데이트하고, 관련 없는 구성은 보존하며, 쓰기 전에 .magaza-mcp-yedek 백업을 생성하고, 원자적 쓰기를 수행합니다.
설정 후 열려 있는 클라이언트 애플리케이션을 다시 시작해야 새 MCP 서버를 로드할 수 있습니다.
설치 확인
상태 및 도구 목록 명령을 사용하여 결과를 확인하세요.
npx magaza-mcp durum
npx magaza-mcp durum --json
npx magaza-mcp araclar
npx magaza-mcp surum
npx magaza-mcp yardimdurum은 연결된 스토어를 보고하고, araclar는 설치된 도구를 나열합니다. ✎로 표시된 도구는 스토어 데이터를 변경할 수 있습니다.
기본 사용법
Mağaza MCP는 MCP 호환 어시스턴트에서 자연어 요청을 통해 사용하도록 설계되었습니다. 클라이언트를 다시 시작한 후 간단한 인벤토리 요청으로 시작하세요.
두 스토어에 있는 내 애플리케이션을 나열하고 각 애플리케이션이 현재 어디에 게시되어 있는지 보여줘.
두 스토어가 모두 연결되면 magaza__genel_bakis는 애플리케이션 목록을 통합하고, 일치하는 iOS 및 Android 제품을 연결하며, 한 스토어에만 있는 애플리케이션을 구분합니다.
구독 가격 비교
특정 국가의 구독 가격을 비교하도록 어시스턴트에 요청할 수 있습니다.
터키에서 Note Keeper의 App Store 및 Google Play 월간 구독 가격은 얼마인가요? 차이가 있나요?
magaza__abonelik_karsilastir 도구는 제품 식별자, 결제 기간 및 국가별 가격을 비교합니다. 또한 국가 코드를 각 스토어에서 요구하는 형식으로 변환합니다.
구매 문제 진단
고객이 결제했지만 프리미엄 액세스를 받지 못한 경우 다음과 같이 요청할 수 있습니다.
고객이 결제했지만 프리미엄 액세스가 활성화되지 않았다고 합니다. 두 스토어의 구매 설정을 확인하고 가능한 원인을 요약해 주세요.
magaza__iap_teshis 도구는 제품이 게시되었는지, 해당 국가에 가격이 등록되어 있는지, Google Play 기본 요금제가 신규 구독자에게 제공되는지 확인합니다. Play 구매 토큰을 제공하면 진단 과정에서 해당 토큰을 검증할 수도 있습니다.
App Store Connect 검사
App Store 전용 도구를 사용하면 애플리케이션, 출시 버전, TestFlight 빌드, 리뷰, 구독 그룹, 구독 가격, 인앱 구매, TestFlight 그룹 및 판매 보고서를 조회할 수 있습니다. 요청 예시는 다음과 같습니다.
- 현재 심사에서 멈춰 있는 App Store 버전은 무엇인가요?
- 어제 업로드한 TestFlight 빌드의 처리가 완료되었나요?
- 지난주에 작성된 별점 1개 및 2개 리뷰를 요약해 주세요.
- 이 애플리케이션의 일일 판매 보고서를 다운로드해 주세요.
스토어 메타데이터와 리뷰 답변도 변경할 수 있지만, 이러한 작업에는 명시적인 확인이 필요합니다.
Google Play 검사
Google Play 도구는 애플리케이션, 출시 트랙, 리뷰, 구독, 기본 요금제 가격, 일회성 제품, 구매 검증, 취소된 구매 및 Android vitals 충돌률을 다룹니다. 요청 예시는 다음과 같습니다.
- 프로덕션 트랙에는 어떤 버전이 있으며, 몇 퍼센트의 사용자에게 배포되나요?
- 지난 14일 동안 충돌률이 증가했나요?
- 이 구매 토큰은 유효한가요? 구독은 아직 활성 상태인가요?
- 제공되는 기간의 환불 또는 취소된 구매를 보여 주세요.
Google은 관련 API를 통해 대략 최근 일주일의 리뷰만 제공합니다. 취소된 구매 데이터는 최근 30일로 제한됩니다.
쓰기 작업 안전하게 수행하기
appstore__yorum_yanitla, appstore__metin_guncelle 및 play__yorum_yanitla와 같은 도구는 스토어 데이터를 변경할 수 있습니다. 이러한 도구는 최초 요청 시 즉시 실행되지 않습니다. 대신 서버가 제안된 작업과 예상 요청 본문을 반환합니다.
제안을 검토한 후 승인하고, 다음과 같이 어시스턴트가 작업을 반복 실행하도록 하세요.
onayla=true이 확인 절차는 MCP 클라이언트의 인터페이스에만 의존하지 않고 서버에서 강제됩니다.
읽기 전용 모드 활성화
감사, 보고 또는 신중한 실험을 위해 서버를 읽기 전용 모드로 시작할 수 있습니다.
npx magaza-mcp --salt-okunur다음 설정을 사용할 수도 있습니다.
SALT_OKUNUR=1두 스토어가 연결된 상태에서 읽기 전용 모드를 사용하면 노출되는 도구 목록이 27개에서 24개로 줄어듭니다. 쓰기 전용 도구는 사라지므로 모델이 해당 도구를 보거나 호출할 수 없습니다. 일반 magaza__cagir 디스패처는 읽기 작업에도 필요하므로 계속 사용할 수 있지만, 읽기 전용 모드에서는 쓰기 작업을 거부합니다.
전체 API 카탈로그 사용
집중형 도구는 일반적인 워크플로를 다루지만, Mağaza MCP는 1,440개의 API 작업에도 액세스할 수 있습니다. 모든 작업을 모델 컨텍스트에 배치하는 대신 세 가지 일반 도구를 제공합니다.
magaza__endpoint_ara는 연결된 스토어의 API 카탈로그를 검색하고 일치하는 작업 이름, HTTP 메서드, 경로 및 매개변수를 반환합니다.magaza__sema는 작업의 요청 본문 스키마를 표시하며, POST 또는 PATCH 요청 전에 특히 유용합니다.magaza__cagir는 선택한 작업을 호출하고 경로 매개변수를 자동으로 채웁니다.
유용한 고급 프롬프트는 다음과 같습니다.
연결된 스토어 API에서 이 리소스를 관리하는 엔드포인트를 검색해 주세요. 쓰기를 시도하기 전에 요청 스키마를 보여 주세요.
카탈로그는 Apple의 공식 App Store Connect OpenAPI 사양과 Google의 Android Publisher 및 Play Developer Reporting 검색 문서에서 생성됩니다. 더 이상 사용되지 않는 Apple 작업이 기능에 접근할 수 있는 유일한 경로인 경우에는 계속 검색할 수 있지만, 요약이 [ESKİMİŞ]로 시작하며 검색 결과 순위는 낮게 표시됩니다.
도구 격리 이해하기
서버는 다음과 같은 여러 설계 규칙을 통해 스토어가 서로 섞이지 않도록 합니다.
- 모든 스토어 전용 도구에는 명시적인 접두사가 있습니다.
appstore__접두사가 붙은 도구는 Google Play를 호출하지 않으며,play__도구는 Apple을 호출하지 않습니다.- 선택되지 않은 스토어의 도구는 메모리에 로드되거나 모델에 표시되지 않습니다.
- 두 스토어가 활성화된 경우에만 스토어 간 도구가 존재합니다.
- 디스패치 도구가 허용하는
magaza인수는 설치 중 구성된 스토어로 제한됩니다.
스토어 두 곳을 사용하는 설치에서는 27개의 도구가 로드됩니다. App Store 전용 설치에서는 14개, Play 전용 설치에서는 13개가 로드됩니다. 이를 통해 MCP 컨텍스트가 구성된 환경에 맞게 유지됩니다.
고급 보안 팁
- 자격 증명을 채팅에 붙여넣지 마세요: 직접
npx magaza-mcp kur를 실행하고 로컬 마법사를 통해 자격 증명 경로를 입력하세요. - 분석에는 읽기 전용 모드를 사용하세요: 릴리스, 검토, 가격, 구매 또는 상태 정보만 필요한 경우 이 모드를 활성화하세요.
- 제안된 쓰기 작업을 모두 검토하세요:
onayla=true를 승인하기 전에 애플리케이션, 리소스, 로케일 및 요청 본문을 확인하세요. - 최소 권한을 부여하세요: 필수 엔드포인트에 더 많은 액세스 권한이 명시적으로 필요한 경우를 제외하고 Apple에서는 App Manager를 사용하고, Google 서비스 계정은 관련 애플리케이션으로 제한하세요.
- 시스템 시간을 정확하게 유지하세요: Apple JWT의 유효 기간은 20분이므로 시계가 크게 어긋나면 인증에 실패할 수 있습니다.
서버는 경로 매개변수를 검증하고 인코딩하며, . 및 ..와 같은 경로 탐색 시도를 거부하고, 절대 URL의 호스트를 검증합니다. 네트워크 트래픽은 Apple API, Android Publisher API, Play Developer Reporting API 및 Google OAuth 토큰 엔드포인트로 제한됩니다.
문제 해결
Apple에서 401 반환
Key ID, Issuer ID 및 .p8 파일이 동일한 App Store Connect API 키에 속하는지 확인하세요. 시간이 잘못 설정된 JWT는 거부될 수 있으므로 시스템 시계를 확인하세요. 또한 해당 파일이 StoreKit 키나 푸시 알림 키가 아닌지 확인하세요.
Apple에서 403 반환
API 키에 해당 작업에 필요한 역할이 없을 수 있습니다. App Manager는 대부분의 워크플로를 지원하지만, 사용자 관리 및 일부 보고서에는 추가 권한이 필요합니다. 역할과 관계없이 계약, 세금 및 은행 정보는 API를 통해 가져올 수 없습니다.
Google Play에서 403 반환
서비스 계정이 Play Console에 초대되었고 대상 애플리케이션에 액세스할 수 있는지 확인하세요. 권한 변경 사항이 적용되는 데 몇 분 정도 걸릴 수 있습니다. 또한 Cloud 프로젝트에서 Android Publisher API와 Play Developer Reporting API가 활성화되어 있는지 확인하세요.
문제가 기존 inappproducts 엔드포인트와 관련된 경우 애플리케이션이 Google의 새로운 제품 모델을 사용할 수 있습니다. play__urunler 도구는 먼저 oneTimeProducts를 시도하고 필요한 경우 기존 모델로 대체하여 처리합니다.
트랙 정보가 느리게 표시됨
Google Play는 수정 세션을 통해 출시 트랙 정보를 제공합니다. 읽기 도구는 세션을 생성하고 데이터를 읽은 다음 커밋하지 않고 종료하므로 스토어 변경 사항은 발생하지 않습니다. 이 과정에는 추가 HTTP 요청이 필요하므로 시간이 더 오래 걸릴 수 있습니다.
개발 환경 설정
프로젝트 자체를 작업하려면 저장소를 복제하고 종속성을 설치하세요:
git clone https://github.com/tunaarikaya/magaza-mcp.git
cd magaza-mcp
npm install
npm run build
npm run kontrol
npm run devnpm run build는 TypeScript 소스를 컴파일하고, npm run kontrol은 파일을 생성하지 않고 타입 검사를 실행하며, npm run dev는 감시 모드 컴파일을 시작합니다.
spec/ 아래의 세 사양 파일에서 API 카탈로그를 다시 생성하려면 다음을 실행하세요:
node scripts/uret-katalog.mjs생성된 작업 카탈로그는 src/katalog/ 아래에 저장됩니다. 작업 목록은 수동으로 관리하도록 설계되지 않았습니다.
결론
Mağaza MCP는 하나의 MCP 호환 어시스턴트에서 App Store Connect와 Google Play를 운영할 수 있는 실용적인 방법을 제공합니다. 스토어 간 도구를 사용하면 가격 비교, 애플리케이션 목록 확인 및 구매 진단을 간소화할 수 있으며, 검색 가능한 전체 API 카탈로그를 통해 자주 사용하지 않는 작업도 처리할 수 있습니다. 로컬 자격 증명 처리, 확인 단계, 읽기 전용 모드 및 텔레메트리 부재 덕분에 스토어 액세스를 통제해야 하는 워크플로에 적합합니다.