Merchant API MCP 액세스 서비스 (알파)

Merchant API 모델 컨텍스트 프로토콜 (MCP) 액세스 서비스를 사용하여 판매자 센터 데이터 및 분석 정보에 대한 승인된 액세스 권한을 얻어 새로운 에이전트형 환경과 자동화된 워크플로를 빌드합니다.

개요

Merchant API MCP 액세스 서비스는 LLM, 에이전트, 코딩 어시스턴트가 판매자 센터 데이터를 기반으로 새로운 에이전트형 환경과 자동화된 워크플로를 빌드하고 오케스트레이션할 수 있는 표준화된 보안 브리지를 제공합니다.

특히 판매자 센터 데이터와 Google에서 생성한 보고서 및 분석 정보에 대한 승인된 액세스 권한을 통해 다음과 같은 사용 사례를 해결하기 위해 읽기 전용 및 제한된 쓰기 작업을 실행할 수 있습니다.

  • 제품 비승인 진단 및 해결
  • 실적 보고서 및 분석 정보 생성
  • 자동 개선 선택 검토
  • 데이터 소스 생성 및 가져오기

안전 및 액세스 제어

Merchant API MCP 액세스 서비스는 보안을 우선순위로 하여 설계되었습니다.

  • 인증: 도구 실행은 표준 Merchant API 인증에 의거하여 관리되며 OAuth 2.0 또는 서비스 계정 사용자 인증 정보가 필요합니다. 가능한 가장 제한적인 액세스 권한이 있는 사용자 인증 정보를 사용하는 것이 좋습니다.
  • 실행 안전: 도구 공개 상태는 에이전트형 검색에 제한되지 않지만 도구 실행은 특정 API 사용자 인증 정보로 제한됩니다.
  • 보호 수단: 도구는 안전 가드레일로 읽기 전용 작업 및 위험도가 낮은 쓰기 도구 (예: 데이터 소스 생성)로 엄격하게 제한됩니다.

중요 고려사항

Merchant API MCP 액세스 서비스는 알파 버전입니다. 범위와 기능이 확장되고 변경될 수 있습니다.

시작하기 전에 다음 제한사항 및 권장사항을 검토하세요.

변경사항 및 출시 버전

변경사항은 사전 고지 없이 발생할 수 있으며 출시 노트에 게시됩니다.

안전한 테스트

실제 프로덕션 환경에서 이러한 도구를 활용하기 전에 먼저 테스트 계정 또는 비실시간 계정을 사용하여 실험하는 것이 좋습니다.

공유 할당량

Merchant API MCP 액세스 서비스는 표준 Merchant API 호출과 동일한 할당량 풀을 공유합니다. 에이전트를 실행하면 특히 데이터 소스 가져오기의 경우 할당량이 빠르게 소진될 수 있습니다. 프로덕션 서비스 중단을 방지하려면 테스트 계정을 사용하는 것이 좋습니다.

도구 필터링 및 안전

새로운 기능, 특히 쓰기 작업이 향후 추가될 예정입니다. 전체 도구 모음을 노출하는 대신 클라이언트를 기본 제공 도구 필터링으로 명시적으로 구성하는 것이 좋습니다.

사용 가능한 기능 요약

Merchant API MCP 액세스 서비스를 사용하여 에이전트형 방식으로 다음 작업을 실행할 수 있습니다.

  • 정확한 리소스 이름을 사용하여 특정 제품의 자세한 상태 및 보고 컨텍스트를 가져옵니다.
  • 여러 제품을 나열하고 검색 합니다.
  • 인기 제품, 가격 분석 정보, 노출 경쟁, YouTube Shopping 제휴 프로그램 분석 정보에 대한 실적 측정항목, 제품 상태, 분석 정보를 쿼리 합니다.
  • 제품 공개 상태 또는 프로그램 참여에 영향을 미치는 계정 수준 문제를 파악 합니다.
  • 데이터 소스의 업로드 상태를 나열, 생성, 가져오기, 확인 합니다.
  • 인벤토리 전반에서 제품 비승인의 집계된 사유를 나열 합니다.
  • 상품, 이미지, 배송의 자동 개선 설정을 검토 합니다.
  • 특정 판매자 센터 프로그램의 활성 지역, 충족되지 않은 요구사항, 참여 상태를 확인 합니다.

시작하기

IDE, 코딩 어시스턴트 또는 에이전트를 Merchant API MCP 액세스 서비스에 연결하려면 MCP 클라이언트 설정을 업데이트하세요. 예를 들어 Google Agent Studio, Claude Desktop, Antigravity, Visual Studio Code 또는 맞춤 에이전트 프레임워크의 mcp.json 파일을 업데이트합니다.

로컬 Merchant API MCP 액세스 서비스 설정에는 서비스 계정이 필요 합니다. 이 헤드리스 로컬 실행에는 표준 사용자 OAuth가 지원되지 않습니다. 서비스 계정을 만들고 JSON 비공개 키 파일을 다운로드한 후 특정 판매자 센터 ID와 함께 경로를 인수로 제공해야 합니다.

서비스 계정을 만들고 다운로드하는 방법에 관한 자세한 안내는 서비스 계정 가이드 를 참고하세요.

클라이언트 구성

구성 설정:

Antigravity

Antigravity 문서의 안내를 따르세요.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Claude Desktop

Claude Desktop 문서의 안내를 따르세요.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

사용 시나리오 예

Merchant API MCP 액세스 서비스를 활용하여 에이전트형 환경과 자동화된 워크플로를 빌드하는 방법을 설명하기 위해 다음 시나리오를 고려해 보세요.

시나리오 1: 제품 비승인 진단 및 해결

특정 제품이 Google 검색 결과에 표시되지 않는 이유를 알고 싶습니다.

사용자 프롬프트:

'혜택 ID'가 'offer123'인 제품이 비승인된 이유는 무엇인가요?

MCP를 사용하는 에이전트 동작:

  1. 에이전트가 list_products 또는 get_product_by_name을 호출하여 제품 상태를 찾습니다.
  2. MCP 서버는 issues(예: '잘못된 가격 형식' 또는 '배송 값 누락') 목록을 포함한 제품 상태를 반환합니다.
  3. 에이전트는 문제를 분석하고 근본 원인을 설명하며 해결 방법을 제안합니다 (예: 가격 정보 업데이트).

시나리오 2: 자동 개선 선택 검토

배송 자동 개선이 활성 상태인지 확인하고 싶습니다.

사용자 프롬프트:

'배송 자동 개선이 사용 설정되어 있나요?'

MCP를 사용하는 에이전트 동작:

  1. 에이전트가 get_automatic_improvements를 호출하여 계정 수준 설정을 가져옵니다.
  2. MCP 서버는 이미지, 상품, 배송 개선의 상태를 보여주는 구성을 반환합니다.
  3. 에이전트는 배송 개선이 활성 상태인지 확인하거나 사용 중지된 경우 사용 설정 방법을 설명합니다.

시나리오 3: 실적 보고서 및 분석 정보 생성

판매자 센터 UI를 탐색하지 않고 최근 실적을 빠르게 확인하고 싶습니다.

사용자 프롬프트:

'지난주 클릭수 기준 실적이 가장 우수한 제품 5개를 보여 주세요.'

MCP를 사용하는 에이전트 동작:

  1. 에이전트는 판매자 센터 쿼리 언어 (MCQL) 쿼리 를 구성하여 product_performance_view 테이블을 타겟팅하고 clicks DESC로 정렬하며 5로 제한합니다.
  2. 에이전트는 구성된 쿼리로 report_search를 호출합니다.
  3. MCP 서버는 실시간 보고 데이터베이스에 대해 쿼리를 실행하고 행을 반환합니다.
  4. 에이전트는 결과를 깔끔한 마크다운 테이블로 형식화합니다.

시나리오 4: 데이터 소스 생성 및 가져오기

제품 업데이트를 업로드하기 위해 새 데이터 소스를 추가하고 싶습니다.

사용자 프롬프트:

'판매자 계정의 보조 데이터 소스를 'price-updates'라는 이름으로 만들어 주세요.'

MCP를 사용하는 에이전트 동작:

  1. 에이전트는 지정된 설정으로 create_data_source를 호출하여 새 피드를 등록합니다.
  2. MCP 서버는 데이터 소스를 만들고 고유한 리소스 이름을 반환합니다.
  3. 에이전트는 fetch_data_source를 호출하여 연결된 파일의 다운로드 및 처리를 트리거합니다.
  4. 에이전트는 get_file_upload를 호출하여 업로드 진행률을 모니터링하고 상품의 처리 상태가 성공적인지 확인합니다.

MCP 도구 및 설명

Merchant API MCP 액세스 서비스는 에이전트에 다음 도구를 노출합니다.

MCP 도구 설명
get_product_by_name 정확한 제품 리소스 이름을 사용하여 지정된 판매자의 제품 정보를 가져옵니다. 보고 컨텍스트와 잠재적인 제품 수준 문제가 포함된 자세한 제품 상태를 반환합니다.
list_products 지정된 판매자의 여러 제품을 나열하거나 검색합니다. 여러 제품의 보고 컨텍스트와 잠재적인 제품 수준 문제가 포함된 자세한 제품 상태를 반환합니다.
report_search 보고 테이블을 쿼리하여 제품 실적 측정항목, 제품 상태, 가격 정보, 노출 경쟁을 가져옵니다. 자세한 내용은 보고서 가이드를 참고하세요.
list_data_sources 지정된 판매자의 사용 가능한 데이터 소스를 나열합니다.
get_data_source 특정 데이터 소스의 세부정보를 가져옵니다.
create_data_source 지정된 판매자의 새 데이터 소스를 만듭니다.
fetch_data_source 지정된 판매자의 데이터 소스와 연결된 파일을 가져와 처리합니다.
get_file_upload 지정된 데이터 소스의 최신 파일 업로드 상태를 가져옵니다.
list_accounts 지정된 사용자의 계정을 나열합니다.
list_account_issues 지정된 판매자의 계정 수준 문제를 나열하여 계정 전반의 문제를 파악합니다.
list_programs 참여 상태, 활성 지역, 충족되지 않은 요구사항을 포함하여 지정된 판매자의 프로그램을 나열합니다.
list_aggregate_product_statuses 집계된 제품 수준 문제를 나열하여 제품 데이터의 전반적인 상태를 모니터링합니다.
get_automatic_improvements 상품 업데이트, 이미지 개선, 배송 개선을 포함한 자동 개선 설정을 가져옵니다.