内容
# 工具列表
> 🇬🇧 [English version](README.en.md)
> **如果您在 Wildberries 和 Ozon 上销售商品，请为您的 AI 代理提供直接访问两个后台的权限。** 两个 MCP 服务器位于 Seller API Wildberries 和 Ozon 之上：**793 种方法** （销售、库存、价格、财务、评论、供应、广告），从官方 OpenAPI 规范中收集。数字来自**真实的 API** ，而不是由模型虚构的。 **安全门** 不会意外更改价格或库存。自动分页、多账户、俄语搜索。适用于 Claude Code、Cursor、Codex、Cowork 和 Claude Desktop。
[](LICENSE)
[](https://github.com/ilyautov/marketplaces-mcp-ru/commits/main)
[](#%E5%90%84%E5%90%8A%E5%86%85%E5%AE%B9)
[](#%E5%AE%89%E8%A3%85)
[](https://github.com/ilyautov/marketplaces-mcp-ru/stargazers)
<!-- social preview: assets/social-preview.png → загрузить в Settings → Social preview.
TODO: сайт marketplaces-mcp-ru.aifrontier.tech (как у humanizer-ru / small-business-ru) -->
## 为什么需要它
**您在两个电商平台上同时销售商品，但数据分散在两个不同的后台。** 销售、库存、价格、财务、评论 – 所有这些都需要手动处理，逐一登录两个后台。普通的 AI 助手通常无能为力：要么需要浏览器登录并面临验证码，要么凭空捏造数据。
`marketplaces-mcp-ru` 从另一个角度切入 – **直接为 AI 代理提供访问两个后台的权限**：
- **来自真实 API 的数据，而非模型臆造。** 销售、库存、利润、财务报告 – 这些都是来自 Wildberries 和 Ozon 的真实数据，而非模型的凭空捏造。
- **所有涉及资金的操作都有安全门槛。** 每个方法都被标记为 `read` / `write` / `destructive`；读取操作可以直接执行，但更改价格或库存需要明确确认。不会意外“降低价格至原来的三分之一”。
## 内部有什么
**不是“一对一”的工具（超过 300 个工具会让 AI 代理感到困惑），而是 8 个通用元工具，覆盖整个 API 目录。**
```
您的 AI 代理
│
▼
8 个元工具 ──► 目录（endpoints.yaml） ──► 核心
搜索 / 描述 / 客户端 · 安全 · 错误
调用 / 调用原始 / 分页 · 注册
获取所有 / ... │
+ 类型工具（wb_get_sales, ozon_get_prices, …） ▼
Wildberries / Ozon HTTPS API
```
**元工具（适用于两个服务器，带有 `wb_` / `ozon_` 前缀）：**
| 工具 | 功能 |
|---|---|
| `*_check_auth` | 检查凭证（不打印密钥） |
| `*_search_methods` | 搜索方法 – **支持中文或英文** |
| `*_describe_method` | 完整规格：方法、主机、路径、范围、安全、限制、文档 |
| `*_call_method` | 调用目录中的任何方法（通过安全门槛） |
| `*_call_raw` | 调用 **任何** 路径，即使在目录之外（100% 覆盖） |
| `*_fetch_all` | 自动分页（offset / last_id / cursor / WB 日期游标） |
以及类型工具（`wb_get_sales`, `wb_get_stocks`, `ozon_get_products`, `ozon_get_prices`, …）和后台工具。
**工作流（场景） – 不是原始端点，而是配方。** `*_list_workflows` / `*_get_workflow` 提供带有解释和典型错误的逐步配方。WB：`sales_pulse`, `stock_health`, `price_audit`, `reorder_planner`, `abc_analysis`, `reviews_pulse`. Ozon: `oos_risk_analysis`, `pricing_analysis`, `unit_economics`, `catalog_sync`, `content_quality_audit`, `abc_analysis`, `reviews_pulse`. 每个步骤都与目录进行核对。
**覆盖 – 来自官方 OpenAPI 规范的 schema-driven：**
| 目录 | 文件 | 方法数量 | 部分数量 |
|---|---|---:|---|
| Wildberries | `wb_mcp/endpoints.yaml` | **307** | 70 |
| Ozon Seller | `ozon_mcp/endpoints.yaml` | **441** | 67 |
| Ozon Performance（广告） | `ozon_mcp/perf_endpoints.yaml` | **45** | 6 |
核心内容（销售/库存/价格/财务/评论）已经过实际验证；其他内容从规范中导入。`call_raw` 可以获取目录中尚未涵盖的所有内容。
### 方法部分 – 两个电商平台涵盖的内容
原始目录部分按业务领域分组：
| 领域 | Wildberries | Ozon |
|---|---|---|
| 销售和订单 | 销售、订单、FBS/DBS/DBW 自提 | FBO/FBS 订单、发货、退货 |
| 库存和仓库 | 库存、卖家仓库、FBS 供应 | 仓库库存、FBO/FBS、库存分析 |
| 价格和折扣 | 价格和折扣、活动日历 | 价格、定价策略、活动 |
| 财务 | 实现财务报告、余额 | 交易、计费、实现、补偿 |
| 内容和商品卡 | 商品卡、类别、属性、媒体 | 商品、属性、类别、证书 |
| 评论和问题 | 评论、问题 | 评论（需要 Premium Plus）、问题和答案 |
| 广告 | 活动管理、统计 | Performance API（独立服务器） |
| 分析 | 销售漏斗、报告 | 分析报告、周转率 |
完整的方法列表 – 直接在聊天中 `*_list_sections`，或搜索：`wb_search_methods("库存")`。
## 可以询问的内容
用中文以普通话询问您的 AI 代理：
```
显示过去一周在 WB 和 Ozon 的销售情况并进行比较
计算补货的必要性 – 根据库存和销售情况计算补货天数
提取过去一个月 WB 的财务报告
哪些 Ozon 商品价格指数为红色 – 降价候选
收集过去一周评分低于 4 星的评论并按商品分类
进行 ABC 分析以获取收入并显示尾部商品
```
如果您不确定从哪里开始 – **询问“您能对我的后台执行什么操作”** 或调用 `wb_list_workflows` / `ozon_list_workflows`：准备好的场景和解释。
## 前后对比
**手动分析“凭感觉”，每次登录一个后台：**
> 登录 WB 后台，粗略查看销售情况。没时间处理 Ozon后台。补货计划凭记忆决定。
**通过 `marketplaces-mcp-ru`：**
> AI 代理通过 API 拉取两个后台的销售和库存数据，计算 ADS 和补货天数，生成“优先补货清单”并附上数字。比较 Ozon 价格与市场指数，标记红色价格。所有数据均来自真实的 API 响应，而非模型臆造，且无风险修改价格（有安全门槛）。
## 安全模型
后台密钥影响价格、库存和资金。每个方法都被分类：
- **read** → 直接执行；
- **write** → 需要 `confirm_write=true`；
- **destructive** → 需要 `confirm_write=true` **和** `i_understand_this_modifies_data=true`。
安全门槛在本地运行 – 无需外部确认。**0 次标记为 read 的突变** 在所有三个目录中 – 通过 CI 中的测试（`test_safety_catalog.py`）验证，而不仅仅是口头承诺：编译失败，如果目录中包含标记为 read 的 PUT/PATCH/DELETE。 此外，`call_method` 即使在突变的动词上也会保险 – 即使过时的 read 也不会将门槛降低到 `write` 以下。
## 安装
详尽的逐步指南适用于任何受众 – 在 **[QUICKSTART.md](QUICKSTART.md)** 中。三种安装方式，达到相同的结果：
1. **最简单 – 请求您的 AI 代理（无需终端）。** 打开 Claude / Cowork 并说：*“安装 WB + Ozon MCP”* – 代理将引导您完成内置的 `install-skill/`。（Cowork 沙盒不会访问您的机器，因此最终的点击仍然由您完成 – 技能仅帮助减少错误。在 Claude Code 中完全自动安装。）
2. **下载并点击。** 从 [GitHub Releases](https://github.com/ilyautov/marketplaces-mcp-ru/releases) 获取 `marketplaces-mcp-ru-v<版本>.zip`，解压， 双击 `install.command`（macOS）/ `install.bat`（Windows），粘贴密钥。 _macOS，第一次：右键 →“打开”→“打开”（绕过 Gatekeeper 以获取下载的文件）。_
3. **技术安装.** `git clone https://github.com/ilyautov/marketplaces-mcp-ru` → `python3 install.py --client <您的客户端>`。
安装程序 **将应用程序复制到稳定位置** (`~/.marketplace-mcp/app`) 并将配置绑定到那里 – 下载或连接的文件夹可以移动和删除，MCP 不会损坏。无需 `pip install` 或编辑 JSON：依赖项在第一次运行时自行安装（本地虚拟环境），只需您提供密钥。**4 个客户端** 通过 `--client`：`claude-desktop` 和 `opencode` 获取记录的配置，`claude-code` 和 `codex` – 准备好的 `* mcp add` 命令。
**获取密钥：** Wildberries – seller.wildberries.ru → 设置 → API 访问；Ozon – seller.ozon.ru → 设置 → API 密钥。密钥存储在 `~/.marketplace-mcp/cabinets.json`（本地，chmod 600，绝不进入存储库）。支持 **多账户** – 从聊天中切换账户（`*_add_cabinet` / `*_use_cabinet`）。
**安装后检查：**
```bash
python3 serve.py ozon --selfcheck
```
## 脚本和目录增长
在 `scripts/` 中：`ingest_specs.py` / `ingest_ozon.py`（从官方规范构建目录），`derive_pagination.py` 和 `fix_items_path_from_examples.py`（分页和 `items_path`），`validate_items_path.py`（**实时** 验证器，在本地运行），`package_release.py`（干净的版本 zip），`smoke_mcp.py`。目录通过添加和幂等增长 – 经过验证的安全性和描述不会被覆盖。
## 测试
```bash
python3 -m pytest tests/ -q # 21 个离线测试，无需令牌
```
## 常见问题
**如何将 AI 连接到 Wildberries 和 Ozon 的 API？** 安装 `marketplaces-mcp-ru` – 两个 MCP 服务器为您的代理（Claude、Cursor、Codex、ChatGPT 通过 MCP）提供直接访问两个后台的权限，无需浏览器和验证码。
**是否有现成的 Wildberries / Ozon Seller API 的 MCP 服务器？** 有，就是这个。来自官方 OpenAPI 规范的 schema-driven 目录：307 个 WB 方法 + 441 个 Ozon + 45 个 Ozon Performance，支持中文搜索，自动分页。
**如何为 WB / Ozon 后台提供 Claude 或 ChatGPT 访问权限？** 通过 MCP。一次性安装服务器（安装程序双击或 `install.py`），输入后台令牌 – 代理直接调用所需的方法。密钥存储在本地（chmod 600），不会进入聊天。
**如何通过 AI 获取 WB / Ozon 的销售、库存、价格和财务数据？** 用中文以普通话询问 – 代理将选择方法（`wb_get_sales`，`ozon_get_prices`，...）或场景并返回真实 API 响应中的数据。
**可以不使用 1C 和编程吗？** 可以。无需 `pip install` 和编辑 JSON：依赖项在运行时自行安装，您只需提供 API 密钥。对于非技术人员，有“请求您的 AI 代理”和双击安装程序。
**与解析器和浏览器机器人有什么区别？** 这是直接的 Seller API 通过令牌，而不是页面解析：无验证码，无阻止，结构化数据。另外，安全门槛不会意外更改价格或库存。
**这是免费的吗？** 是的，开放源码在 MIT 下。获取、修改、扩展。
**是否安全，密钥存储在哪里？** 服务器在本地运行与您的代理相同的位置。密钥存储在 `~/.marketplace-mcp/cabinets.json`（chmod 600），不会进入存储库或聊天。后台录入（更改价格/库存） – 只有在明确确认的情况下。
## 免责声明（请与实时文档核对）
- **WB `Authorization`：** 服务器发送 **原始令牌而非“Bearer”** （已确认）。如果身份验证失败 – 首先检查这一点。
- **导入的方法：路径可靠，HTTP 动词不可靠。** 现场测试发现标记为 GET 的方法实际上是 POST（405）。将导入的记录视为侦察地图：根据文档确认动词/正文或通过 `call_raw` 调用。核心内容（WB 7 类别，Ozon 4 部分）和现场验证的集合 – 可靠。
- **Ozon 漂移版本** （list v3，attributes v4，prices v5）。如果 404 – 检查版本；`ingest_ozon.py` 重新对齐路径。
- **Ozon Performance：** 目前是一个目录工件 + OAuth 绑定根据文档（令牌端点合同未经战斗验证，需要广告凭证）。
- **后台覆盖环境变量：** `cabinets.json` 中的活动后台优先于环境变量。无法解释的 401 /“Client-Id 必须是正整数” – 首先检查存储。
## 这不是什么
这是一个用于 AI 代理的工具，而不是“一键”在线服务或分析师的替代品。核心内容经过战斗验证，但导入的方法请根据文档确认。涉及价格、库存或资金的解决方案始终由您决定 – 安全门槛只是为了防止意外。这是一个 alpha 版本和开源代码：**安装、测试您自己的数据、实验。** 如果您发现问题 – 创建 [issue](https://github.com/ilyautov/marketplaces-mcp-ru/issues)。
自己的代码，最佳模式：架构采用成熟的 marketplace-MCP（schema-driven 目录、安全门槛、统一错误、自动分页）的最强想法，无需依赖外部库。
---
**marketplaces-mcp-ru** – 用于 Wildberries 和 Ozon 后台的开放 MCP 服务器：通过 Seller API 直接获取销售、库存、价格、财务、评论、供应和广告。连接 AI 代理（Claude Code、Cursor、Codex、Cowork、Claude Desktop、ChatGPT 通过 MCP）到 WB 和 Ozon 的 API。来自官方 OpenAPI 规范的 schema-driven 目录（793 种方法），具有安全门槛、自动分页、多账户和中文搜索。免费开源，MIT 许可。数字来自真实的 API 响应，而非模型臆造。
连接信息
猜你喜欢
暂无推荐服务器