YosefHayim/ebay-mcp

AI 어시스턴트에게 eBay의 판매 API (Sell APIs)에 대한 포괄적인 접근 권한을 제공하는 Model Context Protocol (MCP) 서버입니다. 재고 관리, 주문 이행 (order fulfillment), 마케팅 캠페인, 분석, 개발자 도구 등을 위한 **325개의 도구 (tools)**를 포함하고 있습니다.

API 커버리지: 100% (270개의 고유한 eBay API 엔드포인트)

AI 어시스턴트가 이를 직접 설정하도록 하세요! 아래의 프롬프트를 복사하여 Claude, ChatGPT 또는 MCP를 지원하는 모든 AI 어시스턴트에 붙여넣으세요.

AI 설정 프롬프트 복사하기

내 AI 어시스턴트를 위해 eBay MCP 서버를 설정하고 싶습니다. 다음을 도와주세요:
1. eBay MCP 서버 설치:
npm install -g ebay-mcp
...

중요: 이 소프트웨어를 사용하기 전에 다음 면책 조항을 주의 깊게 읽어주십시오.

이 프로젝트는 명시적이든 묵시적이든 어떠한 종류의 보증 없이 "있는 그대로" 제공되는 **오픈 소스 프로젝트 (open-source project)**입니다. 이 소프트웨어를 사용함으로써 귀하는 다음 사항을 인정하고 동의하게 됩니다:

책임 없음 (No Liability): 이 프로젝트의 저자, 기여자 및 유지 관리자는 다음을 포함하되 이에 국한되지 않는, 이 소프트웨어의 사용으로 인해 발생할 수 있는 어떠한 손해, 손실 또는 문제에 대해서도 어떠한 책임도 지지 않습니다:

데이터 손실 또는 손상
재정적 손실
서비스 중단
eBay 계정 정지 또는 해지
eBay 서비스 약관 또는 API 사용 정책 위반
기타 모든 직접적 또는 간접적 손해
귀하의 사용이 eBay의 속도 제한 (rate limits) 및 정책 내에서 유지되도록 보장할 것
eBay 개발자 자격 증명 (developer credentials)을 안전하게 관리할 것
eBay의 데이터 처리 요구 사항을 이해하고 준수할 것
API를 통해 수행되는 모든 작업

자기 책임 하에 사용 (Use at Your Own Risk): 이 소프트웨어는 교육 및 개발 목적으로 제공됩니다. 사용자는 반드시 다음을 수행해야 합니다:

실제 운영 환경에서 사용하기 전에 eBay의 샌드박스 (sandbox) 환경에서 철저히 테스트할 것
자신을 대신하여 호출되는 API 호출 내용을 이해할 것
중요한 데이터의 백업을 유지할 것
API 사용량 및 계정 상태를 모니터링할 것
API 자격 증명(Credentials)을 안전하게 유지할 것
환경 변수(Environment variables)를 적절하게 설정할 것
MCP 서버 사용에 따른 보안적 영향(Security implications)을 이해할 것
보안 모범 사례(Security best practices)를 준수할 것

보증 없음 (No Warranty): 본 소프트웨어는 기능성, 신뢰성 또는 특정 목적에 대한 적합성에 대해 어떠한 보증도 제공하지 않습니다.

본 소프트웨어를 사용함으로써 귀하는 모든 위험을 수용하며, 저자, 기여자 및 유지 관리자에게 발생하는 모든 청구, 손해 또는 책임으로부터 면책하는 것에 동의합니다.

공식 eBay API 지원을 원하시면 eBay Developer Program을 참조하십시오.

⚠️ 면책 조항

기능 (Features)
빠른 시작 (Quick Start)
데모 (Demo)
시각적 설정 가이드 (Visual Setup Guide)
구성 (Configuration)
사용 가능한 도구 (Available Tools)
사용 예시 (Usage Examples)
개발 (Development)
기여하기 (Contributing)
로깅 (Logging)
문제 해결 (Troubleshooting)
리소스 (Resources)
라이선스 (License)

325개의 eBay API 도구

재고, 주문, 마케팅, 분석, 개발자 도구 등을 아우르는 eBay Sell API의 100% 커버리지

9개의 AI 클라이언트 지원

Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI 및 Amazon Q에 대한 자동 구성 지원

OAuth 2.0 지원

자동 갱신을 포함한 완전한 사용자 토큰 관리

타입 안정성 (Type Safety)

TypeScript, Zod 검증 및 OpenAPI로 생성된 타입으로 구축

MCP 통합

AI 어시스턴트와의 직접적인 통합을 위한 STDIO 전송(Transport)

스마트 인증 (Smart Authentication)

사용자 토큰(일일 1만~5만 회 요청)에서 클라이언트 자격 증명(일일 1천 회 요청)으로의 자동 폴백(Fallback) 지원

철저한 테스트 완료

포괄적인 커버리지를 갖춘 958개 이상의 테스트

대화형 설정 마법사

OAuth를 위한 브라우저 자동 실행 및 안내된 구성을 위해 npm run setup 실행

개발자 분석 (Developer Analytics)

속도 제한(Rate limit) 모니터링 및 서명 키(Signing key) 관리
무료 eBay 개발자 계정(eBay Developer Account) 생성
개발자 포털(Developer Portal)에서 애플리케이션 키 생성
Client ID 및 Client Secret 저장

옵션 A: npm에서 설치 (권장)

npm install -g ebay-mcp

옵션 B: 소스에서 설치

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
...

대화형 설정 마법사(setup wizard)가 모든 과정을 대신 처리해 줍니다:

npm run setup

신뢰할 수 있는 대화형 설정을 위해 표준 Node CLI 프롬프트 스택으로 구축되었습니다.

마법사가 수행하는 작업:

eBay 자격 증명(credentials) 구성
OAuth 인증 설정 (더 높은 속도 제한(rate limits)을 위해)
MCP 클라이언트(Claude Desktop 등) 자동 감지 및 구성
모든 설정을 자동으로 저장

Claude Desktop에서 작동하는 eBay MCP Server를 확인해 보세요:

video-tutorial.mp4

설정 마법사(npm run setup)가 OAuth 인증을 자동으로 처리합니다. eBay Developer Portal에서 자격 증명을 찾는 방법은 다음과 같습니다:

1단계: eBay Developer Portal로 이동하여 App ID (Client ID) 및 **Cert ID (Client Secret)**를 복사합니다.

2단계: 앱의 User Tokens 설정에서 RuName (eBay Redirect URL)을 복사합니다.

npm run setup을 실행하고 안내에 따라 자격 증명을 입력하세요. 마법사는 다음을 수행합니다:

OAuth 로그인을 위해 브라우저를 자동으로 엽니다.
eBay 로그인 과정을 안내합니다.
콜백 URL(callback URL)에서 인증 코드(authorization code)를 붙여넣도록 요청합니다.
코드를 토큰(tokens)으로 교환하고 자동으로 저장합니다.
MCP 클라이언트(Claude Desktop 등)를 구성합니다.

성공! 이제 기본값인 일일 1,000회 요청 대신, 일일 10,000~50,000회 요청이 가능한 사용자 토큰 인증을 사용할 수 있습니다.

MCP 클라이언트(Claude Desktop 등)를 재시작하고 AI 어시스턴트를 통해 eBay 도구를 사용하기 시작하세요.

📖

모든 환경 변수(environment variables), OAuth 흐름 단계, 문제 해결(troubleshooting)에 대한 자세한 설명이 포함된 종합적인 구성 가이드를 보려면 구성 문서(Configuration Documentation)를 참조하세요.

설정 마법사(npm run setup)는 .env 파일을 자동으로 생성하고 구성합니다. 참고를 위해 사용되는 환경 변수는 다음과 같습니다:

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox # 또는 "production"
...

클라이언트 자격 증명 (Client Credentials, 기본값): 일일 1,000회 요청 - Client ID와 Secret만으로 자동으로 작동합니다.

사용자 토큰 (User Tokens, 권장): 일일 10,000~50,000회 요청 - 설정 마법사(setup wizard)가 OAuth 흐름을 자동으로 처리합니다. 토큰은 자동으로 갱신됩니다.

상세한 OAuth 설정 및 종합적인 구성 가이드는 구성 문서(Configuration Documentation)를 참조하십시오.

이 서버는 npm run setup을 통한 자동 설정을 지원하는 **9개의 AI 클라이언트 (AI clients)**를 지원합니다.

클라이언트 (Client)	플랫폼 (Platform)	구성 경로 (Config Path)	상태 (Status)
Claude Desktop	macOS, Windows, Linux	`~/Library/Application Support/Claude/claude_desktop_config.json`	✅ 자동 구성됨
Cursor IDE	macOS, Windows, Linux	`~/.cursor/mcp.json`	✅ 자동 구성됨
Zed Editor	macOS, Windows, Linux	`~/.config/zed/settings.json`	✅ 자동 구성됨
Cline	VSCode 확장 프로그램 (Extension)	`~/...globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`	✅ 자동 구성됨
Continue.dev	VSCode, JetBrains	`~/.continue/config.json`	✅ 자동 구성됨
Windsurf (Codeium)	macOS, Windows, Linux	`~/.codeium/windsurf/mcp_config.json`	✅ 자동 구성됨
Roo Code	VSCode 확장 프로그램 (Extension)	`~/...globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`	✅ 자동 구성됨
Claude Code CLI	터미널 (Terminal)	`~/.claude.json`	✅ 자동 구성됨
Amazon Q Developer	AWS	`~/.aws/amazonq/mcp.json`	✅ 자동 구성됨

구성 요구 사항 (Configuration Requirements):

MCP 프로토콜 (Protocol) 버전: 1.0 이상
전송 (Transport): STDIO (기본값) 또는 HTTP
Node.js 런타임 (Runtime): 18.0.0 이상

모든 클라이언트를 위한 빠른 설정 (Quick Setup):

npm install -g ebay-mcp
npx ebay-mcp setup # 대화형 설정 마법사 - 설치된 클라이언트를 자동 감지합니다

설정 마법사는 설치된 AI 클라이언트를 자동으로 감지하여 구성을 완료해 줍니다.

운영 환경(production)에서 사용하려면 eBay API의 속도 제한 (rate limits)을 이해하는 것이 매우 중요합니다:

사용자 자격 증명 (Client Credentials, 기본값):

일일 제한: 일일 1,000회 요청
적합한 용도: 개발, 테스트, 저용량 운영
설정: Client ID와 Secret만으로 자동 설정

사용자 토큰 (User Token, 권장):

일일 제한 (Daily Limit): 하루 10,000~50,000회 요청 (계정 유형에 따라 다름)
최적 용도 (Best For): 운영 환경 (Production), 대량 작업
설정 (Setup): OAuth 흐름 필요 (ebay_get_oauth_url 도구 사용)

계정 유형별 속도 제한 (Rate Limit Tiers):

개인 개발자 (Individual Developer): 일일 10,000회 요청
상업용 개발자 (Commercial Developer): 일일 25,000회 요청
엔터프라이즈 (Enterprise): 일일 50,000회 이상 요청 (맞춤형 제한)

속도 제한 권장 사항 (Rate Limit Best Practices):

운영 환경의 워크로드에는 사용자 토큰 (User Token)을 사용하세요.
속도 제한 오류 발생 시 지수 백오프 (Exponential Backoff)를 구현하세요.
가능한 경우 응답을 캐싱 (Cache) 하세요.
eBay 개발자 포털 (eBay Developer Portal)에서 사용량을 모니터링하세요.
API가 지원하는 경우 일괄 작업 (Batch operations)을 수행하세요.
더 높은 제한을 위해 개발자 계정 등급 업그레이드를 고려하세요.

속도 제한 처리 (Handling Rate Limits):

속도 제한에 도달하면 API는 429 상태 코드를 반환합니다. 서버는 다음과 같이 동작합니다:

지수 백오프 (Exponential Backoff)를 사용하여 자동으로 재시도합니다.
속도 제한 오류를 사용자에게 알립니다.
사용자 토큰 (User Token) 인증으로의 업그레이드를 제안합니다.

현재 사용량 확인 (Check Current Usage):

eBay 개발자 포털 (eBay Developer Portal)에서 API 사용량을 모니터링하세요.

서버는 다음 카테고리로 분류된 100% API 커버리지를 가진 **325개의 도구 (Tools)**를 제공합니다:

계정 관리 (Account Management)

정책 (Policies), 프로그램 (Programs), 구독 (Subscriptions), 판매세 (Sales Tax)
재고 관리 (Inventory Management)
아이템 (Items), 오퍼 (Offers), 위치 (Locations), 일괄 작업 (Bulk operations), SKU 위치 매핑 (SKU location mapping)
주문 이행 (Order Fulfillment)
주문 (Orders), 배송 (Shipping), 환불 (Refunds), 분쟁 (Disputes), 결제 분쟁 증거 (Payment dispute evidence)
마케팅 및 프로모션 (Marketing & Promotions)
캠페인 (Campaigns), 광고 (Ads), 프로모션 (Promotions), 입찰 (Bidding), 일괄 작업 (Bulk operations)
분석 (Analytics)
트래픽 보고서 (Traffic reports), 판매자 표준 (Seller standards), 지표 (Metrics)
커뮤니케이션 (Communication)
구매자-판매자 메시징 (Buyer-seller messaging), 협상 (Negotiations), 알림 (Notifications), 피드백 (Feedback)
메타데이터 및 분류 체계 (Metadata & Taxonomy)
카테고리 (Categories), 아이템 속성 (Item aspects), 정책 (Policies)
개발자 도구 (Developer Tools)
속도 제한 (Rate limits), 서명 키 (Signing keys), 클라이언트 등록 (Client registration)
토큰 관리 (Token Management)
OAuth URL 생성 (OAuth URL generation), 토큰 관리 (Token management)

도구 예시 (Example Tools):

ebay_get_inventory_items

모든 재고 아이템 목록 조회

ebay_get_orders

판매자 주문 조회

ebay_create_offer

새로운 리스팅 오퍼 생성

ebay_get_campaigns

마케팅 캠페인 조회

ebay_get_oauth_url

OAuth 인증 URL (authorization URL) 생성

전체 도구 목록은 src/tools/definitions/를 참조하세요.

eBay MCP 서버를 통해 수행할 수 있는 몇 가지 일반적인 작업은 다음과 같습니다:

사용자: "제 eBay 계정에 대한 OAuth 인증 설정을 도와줄 수 있나요?"

어시스턴트: ebay_get_oauth_url 도구를 사용하여 인증 URL을 생성합니다. 사용자가 해당 URL을 방문하여 권한을 승인하면, 어시스턴트가 .env 파일에 리프레시 토큰 (refresh token)을 구성하도록 도와줍니다.

결과: 일일 API 요청 제한이 1,000회에서 10,000~50,000회로 증가합니다.

사용자: "eBay에 있는 내 모든 활성 리스팅 (active listings)을 보여줘"

어시스턴트: ebay_get_inventory_items를 사용하여 모든 재고 항목을 가져옵니다.

결과: SKU, 수량 및 상태가 포함된 모든 제품의 포맷팅된 목록을 표시합니다.

사용자: "지난 7일 동안 처리되지 않은 모든 주문을 가져와줘"

어시스턴트: 날짜 필터 및 이행 상태 (fulfillment status) 파라미터를 사용하여 ebay_get_orders를 호출합니다.

결과: 배송 처리가 필요한 대기 중인 주문 목록을 반환합니다.

사용자: "내 전자제품 카테고리에 대한 프로모션 리스팅 캠페인을 생성해줘"

어시스턴트: ebay_create_campaign 및 관련 마케팅 도구를 사용하여 광고 캠페인을 설정합니다.

결과: 지정된 예산과 대상 항목으로 새로운 캠페인이 생성됩니다.

사용자: "'Vintage Watches' 카테고리의 모든 품목 가격을 10% 할인된 가격으로 업데이트해줘"

어시스턴트: ebay_get_inventory_items를 사용하여 카테고리별로 필터링한 후, ebay_update_offer를 사용하여 대량 가격 변경을 적용합니다.

결과: 조건에 맞는 모든 품목의 가격이 새 가격으로 업데이트됩니다.

Node.js >= 18.0.0
npm 또는 pnpm
eBay 개발자 계정 (Developer Account)

git clone https://github.com/YOUR_USERNAME/ebay-mcp.git
cd ebay-mcp
npm install
...

명령 (Command)	설명 (Description)
`npm run build`	TypeScript를 JavaScript로 컴파일 (Compile)
`npm start`	MCP 서버 실행
`npm run dev`	핫 리로드 (Hot reload) 기능과 함께 서버 실행
`npm test`	테스트 스위트 (Test suite) 실행
`npm run setup`	대화형 설정 마법사 (Interactive setup wizard) 실행
`npm run sync`	스펙 (Specs) 동기화, 타입 (Types) 생성, 누락된 엔드포인트 (Endpoints) 탐색
`npm run diagnose`	설정 및 연결 상태 확인
`npm run check`	타입 체크 (Typecheck) + 린트 (Lint) + 포맷 체크 (Format check) 실행
`npm run fix`	린트 및 포맷 이슈 자동 수정

eBay에서 새로운 API 엔드포인트 (Endpoints)를 출시하면, 동기화 도구를 사용하여 누락된 항목을 식별하세요:

npm run sync

이 단일 명령은 다음을 수행합니다:

eBay로부터 최신 OpenAPI 스펙 (Specs) 다운로드
스펙으로부터 TypeScript 타입 (Types) 생성
어떤 엔드포인트가 구현되었는지 분석
도구가 필요한 누락된 엔드포인트 보고

새로운 엔드포인트를 추가하기 위한 워크플로우 (Workflow):

npm run sync를 실행하여 누락된 엔드포인트 식별
dev-sync-report.json을 확인하여 전체 목록 파악
src/tools/definitions/에 새로운 도구 (Tool) 생성
src/api/에 API 메서드 (Method) 추가
tests/에 테스트 작성
npm run check && npm test 실행

ebay-mcp/
├── src/
│ ├── index.ts # MCP 서버 진입점 (Entry point)
...

YosefHayim/ebay-mcp

요약

핵심 포인트

video-tutorial.mp4

댓글