野生浆果API-MCP服务器

Name: 野生浆果API-MCP服务器
Author: dmitriipolushin

作者：dmitriipolushin4 星标更新：2025-05-21

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Wildberries API MCP服务器使用指南

简介

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

方法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

# 使用Docker Compose启动服务器
docker-compose up -d

# 停止服务器
docker-compose down

检查安装

您可以发送一个请求到健康检查端点来确认服务器是否正常工作：

curl http://localhost:3000/health

您应该会收到类似以下的响应：

{
  "status": "ok",
  "timestamp": "2023-05-21T12:34:56.789Z"
}

可用的API工具

MCP服务器提供了以下几组端点：

1. 推广统计（Promotion Statistics）

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. 销售漏斗（Sales Funnel）

POST /api/nm-report/detail - 获取商品卡片的周期统计数据
POST /api/nm-report/detail/history - 获取商品卡片的日统计数据
POST /api/nm-report/grouped/history - 获取按类别、品牌和标签分组的商品卡片统计数据

3. 搜索查询（Search Queries）

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. 库存报告（Stocks Report）

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报告（Seller Analytics 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 - 获取报告文件

使用示例

获取广告活动统计

// 使用fetch
const response = await fetch('http://localhost:3000/api/adv/fullstats', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': '您的WILDBERRIES_API_TOKEN'
  },
  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_TOKEN'
  }
});

console.log(response.data);

典型使用场景

1. 监控广告活动效果

场景： 您希望定期跟踪广告活动的效果并分析关键指标。

使用MCP解决方案：

设置每日任务，请求所有活跃活动的统计信息。
将获取的数据保存到数据库中进行历史分析。
创建仪表板，显示关键指标（如点击率、转化率、花费）。

代码示例：

// 获取活动统计
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创建报告生成任务。
等待生成完成并下载报告。
将数据导入分析工具进行分析。

代码示例：

// 创建报告生成任务
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); // 一分钟后再检查

获取API令牌

为了通过MCP服务器使用Wildberries API，您需要一个API令牌。以下是获取方法：

登录Wildberries卖家中心

访问seller.wildberries.ru并登录。
进入API设置

登录系统后，进入“设置”部分（通常可以从菜单或个人资料中找到）。
进入API管理

查找“API”、“API访问”或“集成”部分。
创建新的API令牌
- 点击“创建新令牌”或类似的按钮
- 选择令牌所需的访问权限：
  - 对于MCP服务器WB API，您需要：
    - “分析”类别的权限，用于销售漏斗和搜索查询
    - “推广”类别的权限，用于广告统计
- 为令牌命名（方便识别）
- 如需设置有效期（或保持永久有效）
生成并保存令牌

填写必要信息后，点击“生成”或“创建”以生成API令牌。

重要提示：务必复制并安全保存您的令牌！出于安全考虑，完整的令牌只会显示一次。

故障排除

常见问题

连接失败：确保服务器已启动且端口可用。
认证错误：检查您的Wildberries API令牌是否有效且具有所需权限。
请求频率限制：服务器处理Wildberries API的请求频率限制，但如果超过允许的请求次数，您可能需要等待一段时间。

查看日志

当使用Docker或Docker Compose启动时，日志存储在挂载为卷的logs目录中。

查看正在运行的Docker容器的日志：

docker logs wb-api-mcp

错误代码

401 - 认证错误（检查您的API令牌）
429 - 请求次数超出限制（稍等片刻）
400 - 不正确的请求（检查请求参数）
403 - 禁止访问（检查您的令牌权限）