Wildberries API MCP Server
Wildberries API MCP 서버 사용 가이드
리포지토리 게시 후 위 배지의
ВАШ_ЛОГИН을 GitHub 계정/조직 이름으로 바꾸세요.
목차
소개
Wildberries API MCP 서버는 Wildberries API와의 상호 작용을 간소화하는 중간 서비스입니다. Wildberries API의 분석 데이터, 프로모션 통계 및 기타 정보에 접근하기 위한 통합 인터페이스를 제공합니다.
MCP 서버는 다음 기능을 수행합니다:
Wildberries API의 다양한 엔드포인트 호출을 단순화합니다
오류 및 요청 빈도 제한을 처리합니다
응답 형식을 통일합니다
중앙 집중식 인증을 제공합니다
설치 및 실행
사전 요구 사항
Node.js (버전 14 이상)
npm 또는 yarn
Docker 및 Docker Compose (선택 사항, 컨테이너화용)
해당 권한이 있는 Wildberries API 토큰
방법 1: Node.js를 통한 직접 설치
# Клонирование репозитория
git clone https://github.com/yourusername/wb-api-mcp-server.git
cd wb-api-mcp-server
# Установка зависимостей
npm install
# Запуск сервера
npm start서버는 기본적으로 3000번 포트에서 실행됩니다. PORT 환경 변수를 설정하여 다른 포트를 지정할 수 있습니다:
PORT=8080 npm start환경 변수
.env.example을 .env에 복사하고 필요에 따라 편집하세요:
cp .env.example .env변수 | 기본값 | 설명 |
|
| 서버가 수신 대기하는 포트 |
|
|
|
|
| IP당 분당 최대 요청 수 |
테스트 및 린터
npm test # запускает Jest + Supertest
npm run lint두 단계 모두 모든 push 및 pull request 시 GitHub Actions에서 자동으로 실행됩니다 (.github/workflows/ci.yml 참조).
방법 2: Docker 사용
# Создание Docker-образа
docker build -t wb-api-mcp-server .
# Запуск Docker-контейнера
docker run -p 3000:3000 -d --name wb-api-mcp wb-api-mcp-server방법 3: Docker Compose 사용
cp .env.example .env
# Запуск сервера с Docker Compose
docker-compose up -d
# Остановка сервера
docker-compose down방법 4: GitHub Container Registry의 기성 이미지
main에 push할 때마다 GitHub Actions가 자동으로 이미지를 빌드하고 게시합니다 (.github/workflows/docker-publish.yml 참조):
docker pull ghcr.io/ВАШ_ЛОГИН/wb-api-mcp-server:latest
docker run -p 3000:3000 -d --name wb-api-mcp ghcr.io/ВАШ_ЛОГИН/wb-api-mcp-server:latest설치 확인
헬스 체크 엔드포인트에 요청을 보내 서버가 올바르게 작동하는지 확인할 수 있습니다:
curl http://localhost:3000/health다음과 유사한 응답을 받아야 합니다:
{
"status": "ok",
"timestamp": "2023-05-21T12:34:56.789Z"
}사용 가능한 API 도구
MCP 서버는 다음과 같은 엔드포인트 그룹을 제공합니다:
1. 프로모션 통계
POST /api/adv/fullstats - 광고 캠페인 통계
GET /api/adv/auto/stat-words - 키워드 클러스터별 자동 캠페인 통계
GET /api/adv/stat/words - 키워드별 캠페인 통계
GET /api/adv/stats/keywords - 자동 캠페인의 키워드별 통계
POST /api/adv/stats - 미디어 캠페인 통계
2. 판매 유입경로
POST /api/nm-report/detail - 기간별 상품 카드 통계 조회
POST /api/nm-report/detail/history - 일별 상품 카드 통계 조회
POST /api/nm-report/grouped/history - 카테고리, 브랜드, 태그별로 그룹화된 상품 카드 통계 조회
3. 검색어
POST /api/search-report/report - 검색어별 기본 보고서 데이터 조회
POST /api/search-report/table/groups - 검색어 그룹별 페이지네이션 조회
POST /api/search-report/table/details - 그룹 내 상품별 페이지네이션 조회
POST /api/search-report/product/search-texts - 상품별 검색 텍스트 조회
POST /api/search-report/product/orders - 상품의 검색 텍스트별 주문 및 포지션 조회
4. 재고 보고서
POST /api/stocks-report/products/groups - 재고 보고서용 상품 그룹별 데이터 조회
POST /api/stocks-report/products/products - 재고 보고서용 상품별 데이터 조회
POST /api/stocks-report/products/sizes - 재고 보고서용 사이즈별 데이터 조회
POST /api/stocks-report/offices - 재고 보고서용 창고별 데이터 조회
5. 판매자 분석 CSV 보고서
POST /api/nm-report/downloads - CSV 보고서 생성
GET /api/nm-report/downloads - 보고서 목록 조회
POST /api/nm-report/downloads/retry - 보고서 재생성
GET /api/nm-report/downloads/file/:downloadId - 보고서 파일 조회
6. EVIRMA PRO 데이터 가져오기
POST /api/evirma/import/keywords-report — «키워드별 캠페인 통계» 보고서 가져오기 (multipart/form-data,
file필드, .xlsx/.xls)POST /api/evirma/import/daily-zone-stats — «일별 및 노출 영역별 캠페인 통계» 보고서 가져오기 (multipart/form-data,
file필드, .xlsx/.xls)
EVIRMA PRO 보고서 가져오기
EVIRMA PRO — WB «잼» 공식 구독 데이터를 포함한 고급 Wildberries 광고 분석을 제공하는 유료 Chrome 확장 프로그램(월 699루블)입니다. EVIRMA에는 공개 API가 없으며, 플러그인 인터페이스에서 수동으로만 데이터를 내보낼 수 있습니다. 이 서버는 해당 내보내기 파일을 수신하여 구조화된 JSON으로 변환합니다.
파일을 얻는 방법
EVIRMA PRO에서 키워드별 광고 캠페인 통계를 엽니다.
테이블을 내보냅니다 (내보내기 버튼은 PRO 버전에서만 사용 가능).
생성된
.xlsx파일을 아래 엔드포인트에 업로드합니다.
요청 예시
curl -X POST http://localhost:3000/api/evirma/import/keywords-report \
-H "api-key: ВАШ_ТОКЕН_WILDBERRIES_API" \
-F "file=@Экспорт_..._cmp-advert-keywords-stats_....xlsx"응답 형식
각 행(키워드/클러스터)은 EVIRMA 내보내기에서 그룹화된 것과 동일하게 그룹화된 지표와 함께 반환됩니다:
{
"error": false,
"source": "evirma-pro-keywords-report",
"rowCount": 421,
"data": [
{
"cluster": "5w40",
"traffic": { "impressions": 250, "clicks": 9, "ctr": 3.6, "spend": 184, "...": "..." },
"basketsAd": { "baskets": null, "cpl": null, "...": "..." },
"ordersAd": { "orders": null, "revenue": null, "...": "..." },
"jemForecast": { "baskets": null, "orders": null, "...": "..." },
"jemTraffic": { "avgPosition": 98, "visibility": 100, "...": "..." },
"jemBaskets": { "baskets": null, "...": "..." },
"jemOrders": { "orders": null, "revenue": null, "...": "..." }
}
]
}jemForecast, jemTraffic, jemBaskets, jemOrders 그룹에는 WB «잼» 구독 데이터(광고 트래픽뿐만 아니라 전체 트래픽)가 포함되어 있습니다. 이 그룹은 Wildberries에 «잼» 구독이 연결된 경우에만 내보내기에 표시됩니다.
중요: 열 매핑(lib/evirmaKeywordsParser.js)은 2026년 8월 기준 특정 EVIRMA 보고서의 정확한 구조에 연결되어 있습니다. EVIRMA 개발자가 내보내기 형식을 변경하는 경우 이 파일의 COLUMN_MAP을 새 구조에 맞게 업데이트해야 합니다.
«일별 및 노출 영역별 캠페인 통계» 보고서
POST /api/evirma/import/daily-zone-stats는 일별 및 노출 영역(검색/카탈로그)별 광고 통계가 포함된 보고서를 파싱합니다. 각 기간(전체 기간 합계 + 일별)에는 ad(광고), adEfficiency(광고 효율성: 장바구니, 주문, DRR), total(상품의 전체 트래픽 - 광고 + 유기적)의 세 가지 지표 그룹과 해당 영역에 대한 데이터가 있는 경우 선택적 zones.search / zones.catalog 분류가 있습니다.
curl -X POST http://localhost:3000/api/evirma/import/daily-zone-stats \
-H "api-key: ВАШ_ТОКЕН_WILDBERRIES_API" \
-F "file=@Экспорт_..._wb_cmp_advert-stats_....xlsx"{
"error": false,
"source": "evirma-pro-daily-zone-stats",
"rowCount": 27,
"data": [
{
"period": "За период",
"isSummary": true,
"date": null,
"weekday": null,
"ad": { "impressions": 4578, "cpm": 756, "clicks": 298, "spend": 3460, "...": "..." },
"adEfficiency": { "baskets": 33, "orders": 7, "revenue": 46403, "drrByRevenue": 7.46, "...": "..." },
"total": { "views": 26984, "ordersTotal": 43, "revenueTotal": 286865, "...": "..." },
"zones": {
"search": { "sharePercent": 97, "ad": { "impressions": 4438, "...": "..." }, "adEfficiency": { "...": "..." } },
"catalog": { "sharePercent": 3, "ad": { "impressions": 140, "...": "..." }, "adEfficiency": { "...": "..." } }
}
},
{
"period": "16.08.2026 / вс",
"isSummary": false,
"date": "2026-08-16",
"weekday": "вс",
"...": "..."
}
]
}중요: zones의 каталог은 null일 수 있습니다. EVIRMA 내보내기에서 이 행은 카탈로그에 노출이 없는 날에는 완전히 누락됩니다(0이 아닌). 열 매핑(lib/evirmaDailyStatsParser.js)도 현재 EVIRMA 보고서 형식에 연결되어 있습니다.
사용 예시
광고 캠페인 통계 조회
// Использование fetch
const response = await fetch('http://localhost:3000/api/adv/fullstats', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
},
body: JSON.stringify([
{
"id": 8960367,
"dates": [
"2024-04-07",
"2024-04-06"
]
}
])
});
const data = await response.json();
console.log(data);상품 카드 통계 조회
// Использование axios
const axios = require('axios');
const response = await axios.post('http://localhost:3000/api/nm-report/detail', {
"brandNames": ["ВашБренд"],
"objectIDs": [358],
"tagIDs": [123],
"nmIDs": [1234567],
"timezone": "Europe/Moscow",
"period": {
"begin": "2024-04-01 00:00:00",
"end": "2024-04-15 23:59:59"
},
"orderBy": {
"field": "ordersSumRub",
"mode": "asc"
},
"page": 1
}, {
headers: {
'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
}
});
console.log(response.data);일반적인 사용 시나리오
1. 광고 캠페인 효율성 모니터링
시나리오: 광고 캠페인의 효율성을 정기적으로 추적하고 핵심 지표를 분석하려고 합니다.
MCP 사용 솔루션:
모든 활성 캠페인의 통계를 요청하는 일일 작업을 설정합니다.
기록 분석을 위해 수신된 데이터를 데이터베이스에 저장합니다.
핵심 지표(CTR, 전환, 비용)를 표시하는 대시보드를 만듭니다.
코드 예시:
// Получение статистики кампаний
const campaigns = [123456, 789012]; // ID ваших кампаний
const dates = [getDateString(new Date())]; // Сегодняшняя дата
// Формирование запроса
const requestData = campaigns.map(id => ({
id: id,
dates: dates
}));
// Отправка запроса к MCP серверу
const campaignStats = await fetchFromMcp('/api/adv/fullstats', 'POST', requestData);
// Сохранение данных и генерация отчета
saveToDatabaseAndGenerateReport(campaignStats);2. 상품 판매 유입경로 분석
시나리오: 사용자가 카드 조회부터 구매까지 상품과 어떻게 상호 작용하는지 분석하려고 합니다.
MCP 사용 솔루션:
선택한 기간 동안의 상품별 상세 통계를 요청합니다.
각 단계(조회 → 장바구니 추가 → 주문 → 구매)의 전환을 분석합니다.
최적화를 위해 전환율이 낮은 상품을 식별합니다.
코드 예시:
// Получение статистики воронки продаж
const response = await fetchFromMcp('/api/nm-report/detail', 'POST', {
"nmIDs": [/* ваши номенклатуры */],
"timezone": "Europe/Moscow",
"period": {
"begin": "2024-04-01 00:00:00",
"end": "2024-04-30 23:59:59"
},
"page": 1
});
// Анализ конверсий
const products = response.data.cards;
const lowConversionProducts = products.filter(product => {
const stats = product.statistics.selectedPeriod;
return stats.conversions.addToCartPercent < 5 ||
stats.conversions.cartToOrderPercent < 20 ||
stats.conversions.buyoutsPercent < 80;
});
// Генерация отчета по проблемным товарам
generateLowConversionReport(lowConversionProducts);3. 검색 가시성 최적화
시나리오: Wildberries 검색에서 상품의 가시성을 개선하려고 합니다.
MCP 사용 솔루션:
상품별 검색어 보고서를 요청합니다.
어떤 검색어에서 상품이 좋은 순위를 차지하고 어떤 검색어에서 나쁜 순위인지 분석합니다.
순위 개선을 위해 상품 카드를 최적화합니다.
코드 예시:
// Получение отчета по поисковым запросам
const searchReport = await fetchFromMcp('/api/search-report/report', 'POST', {
"currentPeriod": {
"start": "2024-04-01",
"end": "2024-04-30"
},
"positionCluster": "all",
"orderBy": {
"field": "avgPosition",
"mode": "desc"
},
"limit": 100,
"offset": 0
});
// Получение поисковых текстов для конкретного товара
const searchTexts = await fetchFromMcp('/api/search-report/product/search-texts', 'POST', {
"currentPeriod": {
"start": "2024-04-01",
"end": "2024-04-30"
},
"nmIds": [1234567],
"topOrderBy": "openCard",
"limit": 20
});
// Анализ результатов и формирование рекомендаций
analyzeSearchPositionsAndGenerateRecommendations(searchTexts);4. 분석 기반 재고 관리
시나리오: 판매 데이터를 기반으로 창고의 상품 재고 수준을 최적화하려고 합니다.
MCP 사용 솔루션:
재고 및 판매 보고서를 정기적으로 요청합니다.
판매 속도를 기반으로 최적의 재고 수준을 계산합니다.
과잉 또는 부족 재고 상품을 식별합니다.
코드 예시:
// Получение отчета по остаткам
const stocksReport = await fetchFromMcp('/api/stocks-report/products/products', 'POST', {
"nmIDs": [/* ваши номенклатуры */],
"currentPeriod": {
"start": "2024-04-01",
"end": "2024-04-30"
},
"stockType": "",
"skipDeletedNm": true,
"orderBy": {
"field": "avgOrders",
"mode": "desc"
},
"offset": 0
});
// Анализ скорости продаж и остатков
const stockOptimizationReport = stocksReport.data.items.map(item => {
const dailySales = item.metrics.avgOrders;
const currentStock = item.metrics.stockCount;
const daysOfSupply = currentStock / dailySales;
return {
nmId: item.nmID,
name: item.name,
dailySales,
currentStock,
daysOfSupply,
stockStatus: daysOfSupply < 7 ? 'LOW' : daysOfSupply > 30 ? 'HIGH' : 'OPTIMAL'
};
});
// Генерация рекомендаций по управлению запасами
generateStockManagementRecommendations(stockOptimizationReport);5. 고급 CSV 보고서 생성 및 분석
시나리오: Excel 또는 기타 도구에서 심층 분석을 위한 상세 데이터를 얻으려고 합니다.
MCP 사용 솔루션:
MCP를 통해 CSV 보고서 생성 작업을 만듭니다.
생성이 완료될 때까지 기다렸다가 보고서를 다운로드합니다.
분석을 위해 데이터를 분석 도구로 가져옵니다.
코드 예시:
// Создание задачи на генерацию отчета
const reportId = generateUUID();
const createReportResponse = await fetchFromMcp('/api/nm-report/downloads', 'POST', {
"id": reportId,
"reportType": "DETAIL_HISTORY_REPORT",
"userReportName": "Аналитика по товарам за апрель",
"params": {
"nmIDs": [/* ваши номенклатуры */],
"startDate": "2024-04-01",
"endDate": "2024-04-30",
"timezone": "Europe/Moscow",
"aggregationLevel": "day",
"skipDeletedNm": false
}
});
// Проверка статуса генерации (через некоторое время)
setTimeout(async () => {
const reportStatusResponse = await fetchFromMcp('/api/nm-report/downloads', 'GET', {
'filter[downloadIds]': [reportId]
});
const reportStatus = reportStatusResponse.data[0].status;
if (reportStatus === 'SUCCESS') {
// Загрузка отчета
downloadReport(reportId);
} else if (reportStatus === 'FAILED') {
// Повторная попытка генерации
retryReport(reportId);
}
}, 60000); // Проверка через 1 минутуAPI 토큰 발급
MCP 서버를 통해 Wildberries API를 사용하려면 API 토큰이 필요합니다. 발급 방법은 다음과 같습니다:
Wildberries 판매자 개인 계정에 로그인
seller.wildberries.ru로 이동하여 인증합니다.
API 설정 섹션으로 이동
로그인 후 "설정" 섹션(일반적으로 메뉴 또는 프로필에서 사용 가능)으로 이동합니다.
API 관리 섹션으로 이동
"API" 또는 "API 액세스" 또는 "통합" 섹션을 찾습니다.
새 API 토큰 생성
"새 토큰 생성" 또는 유사한 버튼을 클릭합니다
토큰에 필요한 액세스 권한을 선택합니다:
WB API MCP 서버에는 다음이 필요합니다:
판매 유입경로 및 검색어에 대한 분석 카테고리 권한
광고 통계에 대한 프로모션 카테고리 권한
토큰 이름을 지정합니다 (편의를 위해)
필요한 경우 만료일을 설정합니다 (또는 영구로 유지)
토큰 생성 및 저장
필요한 정보를 입력한 후 "생성" 또는 "만들기"를 클릭하여 API 토큰을 생성합니다.
중요: 토큰을 반드시 복사하여 안전하게 보관하세요! 보안상의 이유로 전체 토큰은 한 번만 표시됩니다.
문제 해결
일반적인 문제
연결 거부: 서버가 실행 중이고 포트에 액세스할 수 있는지 확인하세요.
인증 오류: Wildberries API 토큰이 유효하고 필요한 권한이 있는지 확인하세요.
요청 빈도 제한: 서버가 Wildberries API의 요청 빈도 제한을 처리하지만, 허용된 요청 수를 초과한 경우 대기해야 할 수 있습니다.
로그 보기
Docker 또는 Docker Compose로 실행할 때 로그는 볼륨으로 마운트된 logs 디렉토리에 저장됩니다.
실행 중인 Docker 컨테이너의 로그를 보려면:
docker logs wb-api-mcp오류 코드
401 - 인증 오류 (API 토큰을 확인하세요)
429 - 요청 한도 초과 (잠시 기다리세요)
400 - 잘못된 요청 (요청 매개변수를 확인하세요)
403 - 액세스 거부 (토큰 권한을 확인하세요)
Cloudflare Workers에 배포
서버는 Cloudflare Worker로도 배포할 수 있습니다 (wrangler deploy 또는 GitHub에서 Cloudflare Dashboard로의 자동 배포를 통해). Cloudflare는 2026년부터 cloudflare:node 어댑터를 통해 Workers에서 Express 애플리케이션 실행을 공식 지원합니다. 이를 담당하는 파일은 두 가지입니다: wrangler.jsonc (구성)와 worker-entry.mjs (진입점 래퍼). npm start/Docker를 통한 일반 실행은 이 파일들을 사용하지 않으며 필요로 하지 않습니다.
npm run deploy:cloudflare
# или напрямую:
npx wrangler deploy요구 사항: 빌드 환경에서 Node.js ≥20 (Cloudflare Dashboard에서 .nvmrc에 따라 자동으로 설정되거나 Settings → Build의 NODE_VERSION 변수로 설정).
Docker/일반 Node 호스팅과 비교한 중요한 제한 사항:
Rate limiting (
express-rate-limit)은 카운터를 프로세스 메모리에 저장합니다. Workers에서는 isolate가 주기적으로 다시 생성되므로 요청 한도가 상시 실행 서버보다 더 자주 초기화될 수 있습니다. 프로덕션에서 엄격한 제한을 위해서는express-rate-limit대신 (또는 함께) 플랫폼 수준의 Cloudflare Rate Limiting Rules를 권장합니다.요청당 CPU 시간은 Cloudflare 요금제에 의해 제한됩니다 (특히 무료 플랜에서).
/api/evirma/import/*를 통한 대용량.xlsx파일 파싱은 정말 큰 업로드의 경우 한도에 부딪힐 수 있습니다.업로드된 파일 (
multer)은 요청 메모리에서만 처리됩니다. Docker에서도 이미 그랬으며 여기서 달라지는 것은 없습니다.
이런 제약 없이 완전히 예측 가능한 Node 런타임이 필요하다면, 서버가 원래 작성된 일반 Docker 배포(위 참조)를 사용하세요.
보안 및 프로덕션 운영
프로덕션에서는 HTTPS가 필수입니다. 서버 자체는 TLS를 종료하지 않습니다. reverse-proxy(nginx, Caddy, Cloudflare Tunnel 등) 뒤에 배포하세요. 그렇지 않으면
api-key토큰이 평문으로 전송됩니다.토큰은 서버 어디에도 저장되지 않습니다. 클라이언트가 모든 요청에
api-key헤더로 전송하며 Wildberries API로 프록시하는 데에만 사용됩니다./health는 인증을 요구하지 않습니다. 모니터링 및 Docker/Kubernetes healthcheck용으로 설계되었으며 민감한 데이터를 반환하지 않습니다.Rate limiting — IP당 분당
RATE_LIMIT_MAX요청 수의 내장 한도는 Wildberries API에 대한 우발적인 burst 요청을 방지합니다.의존성 및 코드 자동 스캔 — Dependabot (npm/Docker/Actions)과 CodeQL이 매주 및 모든 PR마다 실행됩니다 (
.github/참조).컨테이너는 root가 아닌 권한 없는 사용자 (
appuser)로 실행됩니다.파일 업로드 (
/api/evirma/import/keywords-report)는 15MB 크기와.xlsx/.xls확장자로 제한됩니다. 파일은 메모리에서만 처리되며 (디스크에 저장되지 않음).
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted MCP server for data analysis: CSV profiling, A/B tests, cohorts, funnels, trend forecasts.
Hosted MCP server for the Wavix telecom platform: SMS, voice, 2FA, SIP, numbers, 10DLC, CDRs.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/antondrpq/Wildberries-API-MCP-Server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server