de en es ja ko ru zh

Wildberries API MCP Server

Name: Wildberries API MCP Server
Author: antondrpq

by antondrpq

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Wildberries API MCP 服务器使用指南

Docker publish

请将上方徽章中的 ВАШ_ЛОГИН 替换为发布仓库后您的 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

变量	默认值	描述
`PORT`	`3000`	服务器监听的端口
`NODE_ENV`	`production`	`production` / `development` / `test`
`RATE_LIMIT_MAX`	`100`	每个 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 分支时，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 是一款付费 Chrome 扩展（699 卢布/月），提供 Wildberries 广告的增强分析功能，包括 WB「Джем」官方订阅数据。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（广告效果：购物车、订单、广告支出占比）和 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 导出文件中，对于目录中没有展示的天数，该行完全不存在（而不仅仅是包含零）。列映射（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）——从 2026 年起，Cloudflare 官方支持通过 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 中，隔离实例会定期重新创建，因此请求限制可能比在持续运行的服务器上更频繁地重置——对于生产环境中的严格限流，建议使用平台层面的 Cloudflare Rate Limiting Rules 来代替（或与 express-rate-limit 一起使用）。
CPU 时间按请求受 Cloudflare 套餐限制（尤其是在免费套餐上）——通过 /api/evirma/import/* 解析大型 .xlsx 文件，在处理真正大规模的数据导出时可能会触及该限制。
上传的文件（multer）仅在请求的内存中进行处理——这在 Docker 上本来就是这样，这里没有任何变化。

如果需要一个完全没有这些限制的、完全可预测的 Node 运行时，请使用常规 Docker 部署（见上文），该服务器最初就是为这种部署编写的。

安全与生产运维

生产环境必须使用 HTTPS。 服务器本身不终止 TLS——请将其部署在反向代理（nginx、Caddy、Cloudflare Tunnel 等）之后，否则 api-key 令牌将以明文形式传输。
令牌不会存储在服务器上的任何地方 —— 客户端在每次请求时通过 api-key 请求头将其传递，并且它仅用于向 Wildberries API 进行代理转发。
/health 不需要授权 —— 它用于监控以及 Docker/Kubernetes 健康检查，并且不会返回敏感数据。
Rate limiting —— 内置的每分钟来自单个 IP 的 RATE_LIMIT_MAX 请求限制可防止对 Wildberries API 的意外突发请求。
依赖项和代码的自动扫描 —— Dependabot (npm/Docker/Actions) 和 CodeQL 每周运行，并在每次 PR 时运行（参见 .github/）。
容器以非特权用户（appuser）身份运行，而不是以 root 身份运行。
文件上传（/api/evirma/import/keywords-report）被限制为 15 MB 大小和 .xlsx/.xls 扩展名；文件仅在内存中处理（不会保存到磁盘）。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
mcp
com.api2cart
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
E-commerce & Retail CRM
1
RU Books MCP
io.github.books-service
MCP server for Russian books search, details, and recommendation candidates.
Search Art & Culture Entertainment & Media
2
SelineOAuth
io.github.getseline
MCP server for the Seline Analytics API
Product Management Data Visualization
12

Related MCP Servers

@theyahia/wildberries-mcp
E-commerce & Retail Finance
theYahia
A
license
B
quality
B
maintenance
Wildberries Seller API MCP server providing 15 tools for managing products, prices, stocks, orders, sales, warehouses, supplies, statistics, feedbacks, and ABC analysis with built-in rate limiting and 409 penalty protection.
Updated a month ago (2026-09-06 08:41 UTC)
30
27 npm
16
MIT
Wildberries MCP Server
E-commerce & Retail Search
kulichevskiy
F
license
Not graded
quality
D
maintenance
MCP server for Wildberries API that enables fetching product cards with multi-cabinet support, automatic pagination, and retry logic.
Updated 7 months ago (2026-03-26 09:58 UTC)
1
-
wildberries-mcp
E-commerce & Retail Web Scraping
shndo1337
F
license
Not graded
quality
D
maintenance
MCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.
Updated 3 months ago (2026-07-08 17:15 UTC)
-
mcp-server-wildberries
E-commerce & Retail Finance
dontsovcmc
A
license
A
quality
D
maintenance
MCP server for Wildberries Seller API enabling management of products, orders, supplies, analytics, advertising, and finance through natural language commands.
Updated 5 months ago (2026-05-10 13:00 UTC)
3
2
MIT

Wildberries API MCP 服务器使用指南

目录

简介

安装与运行

必要前提

方法 1：通过 Node.js 直接安装

环境变量

测试与代码检查

方法 2：使用 Docker

方法 3：使用 Docker Compose

方法 4：使用 GitHub Container Registry 中的现成镜像

验证安装

可用的 API 工具

1. 推广统计

2. 销售漏斗

3. 搜索查询

4. 库存报告

5. 卖家分析 CSV 报告

6. EVIRMA PRO 数据导入

导入 EVIRMA PRO 报告

如何获取文件

请求示例

响应格式

「按天和展示区域分组的广告活动统计」报告

使用示例

获取广告活动统计

获取商品卡片统计

典型使用场景

1. 监控广告活动效果

2. 分析商品销售漏斗

3. 优化搜索可见性

4. 基于分析的库存管理

5. 生成和分析扩展 CSV 报告

获取 API 令牌

故障排除

常见问题

查看日志

错误代码

部署到 Cloudflare Workers

安全与生产运维

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

@theyahia/wildberries-mcp

Wildberries MCP Server

wildberries-mcp

mcp-server-wildberries