Amazon Ads MCP Server

Model Context Protocol (MCP) 서버로, Amazon Advertising API와 상호작용하기 위한 도구를 제공합니다. 이 서버는 AI 어시스턴트가 Amazon Ads 캠페인, 키워드, 성과 데이터 등을 액세스하고 관리할 수 있게 해줍니다.

기능

이 MCP 서버는 다음 도구를 제공합니다:

• get_profiles: 사용 가능한 모든 Amazon Ads 프로필/계정 나열

• get_campaigns: 상태 및 유형별 선택적 필터링으로 광고 캠페인 검색

• get_campaign_performance: 캠페인의 성과 지표 조회(노출수, 클릭수, 비용, 판매액)

• get_keywords: 캠페인 또는 광고 그룹의 키워드 검색

• update_keyword_bid: 특정 키워드의 입찰가 업데이트

• create_campaign: 새 광고 캠페인 생성

• get_product_ads: 캠페인 또는 광고 그룹의 제품 광고 검색

Related MCP server: TikTok Ads MCP Server

사전 요구 사항

1. Amazon Ads 계정: 활성 Amazon Ads 계정이 필요합니다

2. API 자격 증명: Amazon Ads API 액세스를 등록하고 다음을 획득하세요:

   • Client ID

   • Client Secret

   • Refresh Token

Amazon Ads API 자격 증명 얻기

1단계: 애플리케이션 등록

1. Amazon Advertising API로 이동

2. Amazon Ads 계정으로 로그인

3. 개발자 센터로 이동하여 새 애플리케이션 생성

4. Client ID와 Client Secret을 받게 됩니다 - 저장하세요!

2단계: Refresh Token 얻기

OAuth 흐름을 통해 refresh token을 얻을 수 있는 도우미 스크립트를 제공합니다:

1. 프로젝트 루트에 .env 파일을 생성하세요:

AMAZON_ADS_CLIENT_ID=your_client_id_here
AMAZON_ADS_CLIENT_SECRET=your_client_secret_here

2. OAuth 도우미 스크립트를 실행하세요:

npm run get-token

3. 브라우저에서 Amazon의 인증 페이지가 열립니다

4. 로그인하고 애플리케이션을 승인하세요

5. 스크립트가 refresh token을 표시합니다 - 이를 .env 파일에 복사하세요

3단계: 리전 확인

광고 리전을 확인하세요:

• NA: 북미 (amazon.com)

• EU: 유럽 (amazon.co.uk, amazon.de 등)

• FE: 극동 (amazon.co.jp 등)

설치

1. 이 저장소를 클론하세요:

git clone <your-repo-url>
cd amazonads-mcp

2. 의존성을 설치하세요:

npm install

3. 프로젝트를 빌드하세요:

npm run build

구성

환경 변수

.env 파일을 생성하거나 다음 환경 변수를 설정하세요:

AMAZON_ADS_CLIENT_ID=your_client_id
AMAZON_ADS_CLIENT_SECRET=your_client_secret
AMAZON_ADS_REFRESH_TOKEN=your_refresh_token
AMAZON_ADS_REGION=NA  # Options: NA, EU, FE
AMAZON_ADS_SANDBOX=false  # Set to true for testing with sandbox API

Claude Desktop 구성

이 서버를 Claude Desktop 구성 파일에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amazonads": {
      "command": "node",
      "args": ["/absolute/path/to/amazonads-mcp/build/index.js"],
      "env": {
        "AMAZON_ADS_CLIENT_ID": "your_client_id",
        "AMAZON_ADS_CLIENT_SECRET": "your_client_secret",
        "AMAZON_ADS_REFRESH_TOKEN": "your_refresh_token",
        "AMAZON_ADS_REGION": "NA"
      }
    }
  }
}

사용 예시

Claude Desktop에서 구성한 후 Claude에게 다음과 같이 요청할 수 있습니다:

• "내 모든 Amazon Ads 캠페인을 보여줘"

• "1월 1일부터 1월 31일까지 캠페인 ID 12345의 성과 지표는 무엇인가요?"

• "캠페인 12345의 모든 키워드를 나열해줘"

• "키워드 67890의 입찰가를 $1.50로 업데이트해줘"

• "$50 일일 예산으로 새 Sponsored Products 캠페인을 생성해줘"

• "캠페인 12345의 모든 제품 광고를 보여줘"

개발

프로젝트 구조

amazonads-mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── amazon-ads-client.ts  # Amazon Ads API client
├── build/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

빌드

npm run build

개발 모드

변경 사항을 감시하고 자동으로 다시 빌드:

npm run watch

서버 테스트

서버를 직접 실행:

npm start

서버는 stdio를 통해 통신하며 MCP 프로토콜 메시지를 기대합니다.

API 지원 범위

이 서버는 현재 다음을 지원합니다:

• Sponsored Products: 캠페인, 키워드, 제품 광고 완전 지원

• Sponsored Brands: 캠페인 관리(부분 지원)

• Sponsored Display: 캠페인 관리(부분 지원)

• Reporting: 기본 성과 지표(단순화된 구현)

중요 참고 사항

1. 속도 제한: Amazon Ads API에는 속도 제한이 있습니다. 현재 클라이언트는 속도 제한 로직을 구현하지 않습니다.

2. Reporting API: get_campaign_performance 도구는 단순화된 구현을 사용합니다. 프로덕션 환경에서는 전체 비동기 보고 흐름을 구현해야 합니다:

   • 보고서 요청 생성

   • 보고서 완료 여부 폴링

   • 보고서 다운로드 및 파싱

3. 오류 처리: API 오류는 호출자에게 반환됩니다. 인증 오류를 방지하려면 자격 증명이 올바르게 구성되었는지 확인하세요.

4. 리전: Amazon Ads 계정에 따라 올바른 리전(NA, EU, FE)을 설정했는지 확인하세요.

보안

• .env 파일을 커밋하거나 API 자격 증명을 노출하지 마세요

• 리프레시 토큰은 안전하게 저장해야 합니다

• 프로덕션 환경에서는 자격 증명 교체 구현을 고려하세요

리소스

• Amazon Ads API 문서

• Model Context Protocol 문서

• MCP TypeScript SDK

라이선스

MIT

기여

기여를 환영합니다! 언제든지 Pull Request를 제출해 주세요.