wb-mcp-server

WB MCP 服务

通过与 AI 助手聊天来运营你的 Wildberries 店铺。 197 个工具覆盖 Wildberries Seller API — 商品卡片、价格、广告、发货、评价、 财务、分析 — 可供 Claude、Cursor、Copilot、Gemini CLI 及其他任何 MCP 客户端使用。专为 WB 卖家打造（Wildberries 是俄罗斯最大的电商平台），适用于运营一个或多个卖家账号、希望通过提问而非点击卖家门户来完成操作的用户。

也在 Ozon 上销售？这里有适用于 Ozon 的同款服务。

该服务已在约 20 个 WB 卖家账号中日常使用超过 5 个月，提供 197 个工具。它是作者自己使用的工作工具，并会根据作者的需求持续更新 — 详情请见此处。

You: Which of my product cards are blocked, and why?
You: Show ad cost share for every campaign this week and pause the ones above 15%.
You: Which warehouses currently have an intake coefficient of 0 or 1?
You: Reply to every new 5-star review with a thank-you note.

可实现的功能

共 197 个工具，按 Wildberries Seller API 区域分组。 完整的编号列表及每个工具的说明见 docs/tools.md。

与通常没有这些功能的类似服务相比，有三项不同之处：

• 多店铺。 每次调用都需要传入 shop_id，因此可以在一次对话中使用两个 WB 卖家账户。只有一个店铺时，可以完全省略 shop_id。
• WB API 诊断。 服务会自行 ping WB 主机，为每个 API 类别发送一个低成本探测请求，解析令牌的有效期和权限范围，并突出显示“降级”情况：曾经可用的工具现在持续失败——这是 WB 更改 API 的可靠迹象。
• 加密令牌。 WB 令牌会经过加密（Fernet）后存储，而不是保存在客户端配置中。

快速开始

选项 1：一条命令，无需 Docker

此服务使用 stdio 通信，这是 Claude Desktop、Cursor、VS Code 和其他 MCP 客户端连接它的方式。无需构建：

uvx wb-mcp-server

也可以通过 pip 安装：

pip install wb-mcp-server
wb-mcp

客户端配置（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "wildberries": {
      "command": "uvx",
      "args": ["wb-mcp-server"],
      "env": {
        "WB_API_TOKEN": "your Wildberries API token",
        "DATA_DIR": "~/.wb-mcp"
      }
    }
  }
}

将 DATA_DIR 指向任意可写目录——店铺、密钥和统计数据都存放在其中。 默认值为 /data，这是 Docker 容器内使用的路径。

选项 2：使用 Docker 和 Web 仪表板

如果你需要仪表板、WB API 诊断和基于浏览器的店铺管理，请使用此选项。你需要 Docker（Docker Desktop 或 OrbStack）以及 Wildberries Seller API 令牌。

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
cp .env.example .env          # fine as-is for a local run
docker compose up -d --build

检查：

curl -s http://localhost:8001/api/health
# {"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}

现在你可以访问：

接下来：

1. 打开 http://localhost:8001/shops → Добавить магазин（添加店铺）→ 粘贴 WB 令牌 → Проверить（测试）。令牌可从 WB Seller Portal （seller.wildberries.ru）获取：Настройки → Доступ к API → Создать токен （设置 → API 访问 → 创建令牌）。令牌有效期为 180 天；诊断页面会显示剩余有效期。
2. 连接 MCP 客户端——请参阅下一节。
3. 对助手说：“列出我的 Wildberries 店铺”——此时应会调用 wb_list_shops 工具。

启动命令逐项说明：

使用 docker compose down 停止服务（数据会保留在 wb_data 卷中）。 日志：docker compose logs -f。

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8001 python -m wb_mcp.app

安装到客户端

服务通过 SSE 使用 MCP：GET /sse 是事件流，POST /messages 用于传递客户端消息。不同客户端对 SSE 的支持有所不同，因此每个客户端都有专属指南——包含 macOS、Linux 和 Windows 的配置路径、可直接粘贴的 JSON，以及有无身份验证令牌的配置方案。

docs/ 中的各客户端指南目前仅提供俄语版。其中的配置是现成的 JSON，包含文件路径和标志，无论语言如何都能看懂。

概览和兼容性表：docs/README.md。

如果客户端提供可自行配置连接的命令，指南会优先介绍该命令，并将编辑 JSON 作为第二种方案。最简便的配置方式是使用 Claude Code：

claude mcp add --transport sse wildberries http://localhost:8001/sse
claude mcp list      # expected: wildberries ... ✔ Connected

多店铺与安全

多个卖家账号。 在 /shops 添加店铺；每个店铺都有自己的 shop_id。 wb_list_shops 会返回店铺列表，197 个工具中的 200 个都将 shop_id 作为第一个 参数（例外是 wb_list_shops 和 wb_degradations）。 如果只有一个店铺，可以省略此参数——服务会自动使用唯一可用的店铺。

重点不是“支持两个账号”，而是策略只需编写一次，就能应用到每个账号：定价规则、 回复评价模板、广告出价上限都可以在一次对话中应用到所有店铺——无需切换账号，也不必 把 API 密钥分散配置在不同客户端中。

可连接的账号数量。 代码中没有限制：shops.json 是一个普通字典，想加多少个都可以。 上限由 Wildberries 决定，而不是由此服务决定：所有账号都通过同一个 IP 地址访问 WB—— 也就是运行此服务的地址，而且速率限制也是按地址计算的。作者自己的估算是：每个地址 连接约 20 个账号仍处于安全范围。超过这个数量，就应将账号分散到多个使用不同地址的服务上。

这比看起来更重要，详见 WB 限制： 有几种方法每分钟只允许 3 次请求，而且任何 4XX 响应都会计为 10 次请求。 如果十几个账号共用一台服务，连续几次格式错误的请求就会以快十倍的速度耗尽配额—— 而且所有店铺会同时触及限制，不只是出错的那个店铺。

可以通过以下方式留意这种情况：

• 后台诊断每次运行时会向每个主机发送一次 /ping（每个主机每 30 秒的限制是 3 次请求）， 并将检查失败和警告记录到历史记录中。你可以提前发现限制即将触发，而不是等到被封锁后才知道。
• 降级检测器可以区分两种情况：多个工具同时降级，意味着按地址进行的限流；单个工具降级， 则意味着 WB 的某个端点发生故障。仪表板会让你一眼看出区别。

令牌存放位置。 在 wb_data 卷中（容器内的 /data）：

• shops.json — 店铺信息，令牌使用 Fernet 加密；
• .encryption_key — 加密密钥，首次启动时生成；
• stats.db — 保存调用统计数据和诊断历史记录的 SQLite 数据库。

密钥与加密数据放在一起，因此加密可以防止单个 shops.json 文件意外泄露（例如备份、 复制粘贴），但无法防止有人获取整个卷。应将数据作为整个卷迁移——详见 DEPLOY.md。

MCP 授权。 .env 中的 MCP_AUTH_TOKEN 变量：

openssl rand -hex 32   # put the value into .env → MCP_AUTH_TOKEN=
docker compose up -d

• 为空（默认值）——任何能通过网络访问此端口的人都可以访问 /sse；
• 已设置——客户端必须在 URL 中发送 Authorization: Bearer <token> 或 ?token=<token>。 第二种方式适用于无法发送自定义请求头的客户端。

两个 MCP 端点都会检查令牌——GET /sse 和 POST /messages。

此服务不会执行以下操作：

• Web 界面（/、/shops、/diagnostics）不会受到令牌保护——任何能通过网络访问此端口的人都可以访问。
• 端口 8001 不适合暴露到互联网。远程访问请使用 Tailscale 或 VPN。
• 此服务不会终止 HTTPS。如果需要从外部通过 TLS 访问，请在前面放置反向代理。

Web 界面：每次调用都清晰可见

在典型的 MCP 服务中，调用会无影无踪：你无法看到助手实际做了什么、耗时多久，或市场返回了 什么内容；只有出错时你才会发现问题。在这里，每次调用都会留下记录，每个店铺都有自己的状态。 对于能在真实店铺中动用真实资金的工具，这不是装饰，而是建立信任的前提。正是五个月来在约 20 个账号上的日常使用，填充了这些页面，也促成了后文的 WB 限制章节。

仪表板 — /

本页顶部显示截图。

所有工具调用的摘要（stats.get_summary()）：

• 调用总数、今日调用数、错误数、平均调用耗时；
• 排名前 10 的工具：调用次数、平均耗时、错误数；
• 最近 50 次调用的动态列表：时间戳、店铺、工具、耗时（毫秒）、成功或失败、错误文本；
• 按店铺筛选——摘要上方有一个“全部 / 特定账户”切换开关。

店铺 — /shops

无需编辑文件或重启容器，就能直接在浏览器中添加和移除账户。每个店铺都有一个 Проверить（“测试”）按钮：它会向 WB 发起一次开销很低的真实请求，立即告知你令牌是否有效，而不是等到第一次实际调用时才发现。列表中的令牌会以掩码形式显示（abc***xyz）。

令牌使用 Fernet 加密，并存储在数据卷中的 shops.json 里；密钥保存在其旁边的 .encryption_key 中。保存或删除店铺时，HTTP 客户端池会重置，因此新令牌会立即生效。

诊断 — /diagnostics

（截图显示的是一个使用虚构令牌的演示店铺：WB 对每次 ping 和每项探测都返回 401，因此整个页面都是红色的。这就是检查失败时的样子——服务器本身没有问题。令牌有效时，“Проверка …”一行会显示 ping 13/13, пробы 20/20，店铺状态为“✅ Здоров”。）

后台会按店铺定期运行检查，间隔为 HEALTH_CHECK_INTERVAL_MIN 分钟（默认 30 分钟）：

• 令牌——到期时间、访问类别、只读和沙盒标志；
• ping 13 个 WB API 主机——每个主机的可用性和延迟；
• 20 项探测——每个 API 类别发起一次开销很低的真实 GET 请求。这些探测能发现“WB 重命名接口导致端点返回 404”之类的问题；
• 通俗易懂的警告：“令牌将在 N 天后过期”，“Content：/content/v2/... 返回 404 — WB 可能更改了 API”；
• 检查历史记录，并自动轮换（保留最近 1000 条记录）；
• 一个可立即运行所有检查的 “立即检查” 按钮。

降级检测器

累积统计数据中最有用的功能。服务器会自动找出过去正常工作、现在却持续失败的工具：最近三次调用均失败，而历史记录中存在成功调用。对于每个这样的工具，它会显示上次成功调用的时间、连续错误次数、最新错误文本以及问题出现的时间。

换句话说，服务器会根据自身统计数据检测出 Wildberries 是否中断或关闭了某个端点，并在你工作时遇到问题之前通知你。它是限流和端点关闭日期说明的实际补充：该部分列出 WB 公布的信息，而这里能捕捉 WB 未公开的变更。

你可以在仪表板中查看，也可以直接在聊天中调用 wb_degradations。

外部监控用 JSON

所有人类可见的信息也都能以机器可读的形式获取：

因此，你可以将此服务接入 Uptime Kuma、Zabbix 或其他监控系统，并在助手告知你令牌失效之前就发现问题。

上下文预算

有两项需要消耗 token：每个会话加载一次的工具定义，以及每次调用都要付出的工具响应。两者都基于真实卖家账号测量，而非估算——scripts/collect_corpus.py 会对只读工具进行快照（在任何内容写入磁盘前屏蔽个人身份信息，语料库不会进入仓库），scripts/measure_corpus.py 则报告其开销。

定义。 配置单个店铺时，197 个工具消耗 17 700 个 token，低于之前的 27 460 个。每个描述都只有一句话；只有一个店铺时，会从架构中移除 shop_id（由服务端补全）；空的架构字段不会序列化。

响应。 真正的问题原来出在少数几个超大的载荷上：

服务端采取了以下措施：

• view: compact | full。 大型工具只返回调用所需的字段；view="full" 会提供原始 API 响应。响应本身会说明隐藏了哪些字段，因此模型知道还能请求哪些内容。
• 截断信号。 如果返回记录数恰好达到 limit，响应会附带数据不完整的警告。没有这个提示，模型就会根据部分数据进行推理，并将其当作完整目录。
• 大小保护。 如果响应超出客户端的输出上限（Claude Code 默认的 MAX_MCP_OUTPUT_TOKENS 为 25 000），服务端会截断响应，并说明从总数中省略了多少条记录，而不是让响应在到达时被静默截断。
• 在 API 不提供筛选功能时由服务端筛选。 WB 会完整返回佣金参考数据；这里用 subject 参数缩小范围。

备注会作为单独的内容块返回，而不是 JSON 中的字段：WB 有一半端点会在顶层返回数组，如果用对象包装，就会破坏所有访问数据的路径。

工具配置集。 不支持工具搜索的客户端每次请求都要加载整个工具目录。WB_TOOLSETS 只保留你会用到的配置集——它们按实际工作任务划分，而非按 WB 文档章节划分，因为审核促销活动时需要同时使用促销、价格和价格隔离工具：

core 配置集——店铺、诊断、降级信息、token 信息——始终启用：出问题时正是最需要诊断信息的时候。已禁用的配置集会列在 wb_list_shops 的描述中；调用已禁用的工具时，会提示它所属的配置集——这样助手就能说明原因，而不是说“无法做到”。

Claude Code 不需要这些功能：它默认启用工具搜索，并按需加载架构。Cursor、Cline、Continue 和 Claude Desktop 会一次性获取完整的 tools/list——这些配置集是为它们准备的。

设计决策

• 202 个范围狭窄的工具，而非少数几个通用工具。 将它们合并为 action 风格的端点虽然能节省定义令牌，但会改变故障类型：你遇到的将不再是“没有此工具”，而是会产生副作用的错误调用；其中一些工具会设置价格并启动广告活动。
• 通过字典分发，而非使用 if 链。 NO_CLIENT_DISPATCH、CLIENT_DISPATCH 和 SHOP_DISPATCH 将名称映射到处理程序，并通过测试断言每个工具都有对应处理程序，且没有处理程序被遗弃。对于 197 个工具，if 链会悄然腐坏。
• 服务会自我诊断。 wb_diagnostics 会 ping 每个 WB 主机，并针对每个 API 类别执行一个轻量级真实请求；wb_degradations 会报告哪些工具过去可用、现在却持续失败。Marketplace API 会在没有通知的情况下发生变化——“是我的令牌出了问题，还是 WB 移动了端点”这个问题必须能通过一次调用得到回答。
• 繁重工具默认使用 compact。 数据集显示，被隐藏的字段是照片 URL、促销历史和仓库时间表，而不是做出决策所依据的数据。响应会说明隐藏了哪些内容，因此不会悄无声息地丢失信息。
• 只有一家店铺时，架构中会移除 shop_id。 在 200 个架构中重复相同的参数块，每个会话要耗费 3 400 个令牌，却没有提供任何信息；服务会自动填入唯一的店铺，并在出现第二家店铺时立即恢复该参数。
• 刻意固定使用 mcp<2。 2.0 低级 API 移除了此服务所依赖的装饰器处理程序；迁移是单独的任务，而且固定版本的位置有文档说明，无需等到运行时才发现。
• 令牌在静态存储时经过加密（使用 Fernet，密钥存放在数据卷中），并在界面中脱敏；数据集收集器会在写入文件前脱敏个人数据，因为订单和聊天负载中包含客户姓名、电话和地址。

工作原理

一个 Docker 容器运行一个 FastAPI 应用，同时承担两个角色： 通过 SSE 提供 MCP 服务，以及提供一个小型 Web UI。各文件各用一段话说明：

• wb_mcp/server.py — MCP 服务本身。包含 202 个 Tool 对象的 TOOLS 列表 （名称、描述、参数的 JSON schema）就是客户端收到的 tools/list 响应内容。调用由三个字典路由：NO_CLIENT_DISPATCH （无需访问 WB）、CLIENT_DISPATCH（需要商店的 HTTP 客户端）和 SHOP_DISPATCH（还需要 shop_id）。这里只定义了 stdio 入口 main()，供只支持 stdio 的客户端使用。
• wb_mcp/client.py — 用于 14 个 Wildberries 主机的 HTTP 客户端。每个商店对应一个 WBClient，它封装了带有令牌的 httpx.AsyncClient；客户端缓存在一个以 shop_id 为键的池中。
• wb_mcp/app.py — FastAPI：用于 MCP 的 GET /sse 和 POST /messages、仪表盘、商店和诊断页面、/api/* JSON API、MCP_AUTH_TOKEN 检查，以及后台健康检查循环。
• wb_mcp/settings.py — 商店和密钥：读取和写入 shops.json、Fernet 加密、迁移旧版单商店 settings.json，以及为 UI 遮盖令牌。 另有一个回退机制：如果设置了 WB_API_TOKEN，就会出现名为 default 的商店。
• wb_mcp/diagnostics.py — 对 WB 主机执行 ping、解码 JWT 令牌（有效期、作用域、沙盒标记）、运行“探测”——每个 API 类别发起一个低成本的真实请求——以及获取 WB 新闻。
• wb_mcp/stats.py — 通过 aiosqlite 使用 SQLite：记录每次工具调用的耗时、成功标记和 shop_id；这些数据用于降级检测器和健康检查历史记录。
• wb_mcp/templates/ — 三个 PicoCSS 页面，无需前端构建步骤。

不太显而易见的细节：

• 只有一个商店时，会自动填入 shop_id。 平时用起来很方便，但一旦添加第二个账户，不带 shop_id 的调用就会开始返回“Укажите shop_id”（“请指定 shop_id”）。
• 每次调用都会写入统计数据，失败的调用也不例外。这正是降级检测器的依据：“以前能用，现在持续失败”说明 WB 更改了 API，而不是你操作有误。请查看 wb_degradations 或仪表盘。
• 每隔 30 分钟执行的后台诊断会向 WB 发起真实请求，并消耗你的速率限制额度。如果这会造成影响，可在 .env 中设置 HEALTH_CHECK_INTERVAL_MIN=0。
• 响应会原样返回，即 WB 的原始 JSON，不做重新封装。这样可让工具的行为更可预测，但请求大型报告时应使用筛选条件，否则答案会占满上下文窗口。
• POST /messages 被挂载为单独的 ASGI 应用（Mount），而不是普通的 FastAPI 路由：handle_post_message 会自行发送 ASGI 响应；如果在路由中调用，框架会再次发送响应，导致每次 POST 时连接都被断开。这就是为何必须在应用内部手动检查此端点的授权。
• mcp 库版本固定为 >=1.0.0,<2。 服务是基于 mcp 1.x 的装饰器 API（@app.list_tools()）编写的；该 API 已在 mcp 2.0 中移除。不要在 pyproject.toml 中取消上限：使用 mcp 2.x 时，服务启动会因 AttributeError: 'Server' object has no attribute 'list_tools' 而崩溃。

环境变量

Wildberries API 限制

这些是 WB 本身的限制，而不是此服务的限制——但助手会经常遇到，最好提前了解。此列表并非从文档中复制而来：它基于五个月的每日调用记录，涵盖约 20 个账户，另有诊断日志作为依据。

• GET /adv/v3/fullstats（广告统计）——每分钟 3 次请求，周期不超过 31 天。
• 销售漏斗 v3——每分钟 3 次请求；最多只能查询最近一周的逐日历史记录。
• /ping——每台主机每 30 秒 3 次（后台诊断会计入此限制）。
• 任何 4XX 响应都会按 10 次请求计入限制（自 2026-06-04 起生效的规则）。在循环中用错一个参数，就会触发速率限制。
• Wildberries 已于 2026-07-15 移除 reportDetailByPeriod。此服务调用 finance-api；旧端点的回退机制已移除，因为该端点已失效。生成销售报告需要令牌具备 Finance 类别权限——否则会收到清晰的错误提示，告知需要重新签发哪些权限，而不是含糊的拒绝信息。
• 无法通过 API 创建 FBW 供货单——只能在卖家门户中创建。wb_fbw_* 工具仅提供信息。
• WB 令牌的有效期为 180 天。wb_token_info 和 /diagnostics 页面会显示剩余有效期。
• WB 返回 429 表示触发了速率限制，而不是请求失败。请等待一分钟后重试。

已根据 dev.wildberries.ru 文档于 2026 年 8 月核实。

技术参考

Wildberries Seller API 主机

诊断

• /diagnostics 页面——按店铺显示：令牌有效期和权限范围、所有 WB API 主机的 ping、各类别探测、检查历史记录，以及“立即检查”按钮。
• 每隔 HEALTH_CHECK_INTERVAL_MIN 分钟执行自动后台检查。
• 降级检测器——在仪表板上突出显示已停止工作的工具。
• MCP 工具：wb_diagnostics、wb_token_info、wb_degradations、wb_api_news。
• GET /api/health——供外部监控使用的 JSON 摘要。
• POST /api/diagnostics/run——立即检查所有店铺。
• GET /api/diagnostics/<shop_id>——单个店铺的完整诊断信息。

项目布局

wb-mcp-server/
├── docker-compose.yml          # port 8001, wb_data volume
├── Dockerfile                  # python:3.12-slim
├── pyproject.toml
├── DEPLOY.md                   # deploying to a dedicated machine, moving the data
├── docs/                       # client setup guides + tool reference
└── wb_mcp/
    ├── server.py       # MCP server: 197 tools, dispatch tables, stdio mode
    ├── client.py       # HTTP clients for the 14 Wildberries APIs
    ├── app.py          # FastAPI: SSE + web UI + auth + health loop
    ├── diagnostics.py  # pings, JWT decoder, probes, API news
    ├── settings.py     # stores and keys (Fernet)
    ├── stats.py        # call statistics and check history (SQLite)
    └── templates/      # PicoCSS: dashboard, diagnostics, shops

部署

将服务迁移到专用机器、迁移店铺、设置开机自启—— 请参阅 DEPLOY.md（俄语）。

Ozon 的同类服务

DeviceIngineering/ozon-mcp-server 是面向另一个电商平台的同类工具（Ozon 是俄罗斯另一个大型电商平台）： 架构相同，带有仪表板和诊断功能的 Web UI 相同，通过 shop_id 处理多个店铺的方式相同，SSE 传输方式相同，连接客户端的方式也相同。设置好一个后，另一个也遵循相同的说明；只有端口和工具集不同。

它们可以在同一台机器上并行运行：端口不同，Docker 卷不同，不会冲突。

它们运行在同一台服务上也不会影响速率限制：两者通过同一个 IP 发出请求，但 Wildberries 和 Ozon 分别计算各自的限额——它们是不同的平台。多店铺部分所述的每个地址可使用的账号数量上限，分别适用于各个平台。

从 API 访问到可用的调价器

此服务让模型能够访问卖家账号。决定价格应该是多少是另一项独立工作，ozon-wildberries-repricer 负责这项工作：它保存参考价格，根据各电商平台的实际费用计算盈亏平衡底价，将会导致售价低于成本的商品从促销活动中移出，并能通过在实际销售中开展受控实验来寻找更优价格。

它在一个地方支持 Ozon、Wildberries 和 Yandex Market，还为 LLM Agent 提供了自己的 HTTP 控制平面，并具备模型所需的防护措施：可能触发 Wildberries 隔离的调价会分多次执行，三分钟后会重新读取价格，因为电商平台有时会对实际上并未执行的更改报告成功；多个 Agent 同时处理同一商品目录时，也不会相互覆盖决策。

无需电商平台账号即可运行：npm run demo 会生成一份模拟商品目录并启动应用。

更新与支持

Wildberries 会不断更改其 API：新增、重命名和停用端点——上文的限制部分列出了实际使用中发现的问题。 此服务是作者日常使用的工具：已在大约二十个卖家账号中连续使用五个多月。更新取决于作者的需求——当下一次更改影响到他自己的店铺时才会更新，而不是按计划进行。这就是提交间隔可能很长的原因：这意味着 WB 在此期间没有造成问题。没有更新时间承诺。

如果急需修复，请发送邮件至 [email protected]。 欢迎提交 Issue 和 Pull Request，作者也会审核。

版本历史：CHANGELOG.md。

许可证

MIT — 详见 LICENSE。

MCP Registry

已发布至官方 MCP Registry：

mcp-name: io.github.DeviceIngineering/wb-mcp-server