marketplace-mcp

一个 MCP 服务器，让 AI 代理能够操作 Wildberries / Ozon / Yandex Market 卖家账户：类型化的读取工具、多账户支持、数据规范化、速率限制、审计和加密凭据。不是通用代理——工具按市场划分命名空间（wb_*、ozon_*、ym_*），每个工具都会检查连接权限并返回统一的规范化结构。

状态：v0.3 —— 覆盖全部三个市场的读取面。 核心、WB / Ozon / Yandex Market 适配器、17 个工具。尚未实现：带预览/确认的 WRITE、历史收集器、广告和财务。参见路线图。

项目主旨

一个问题，一种响应结构，与平台无关。三个市场对商品、库存和订单的建模互不兼容：在 WB 上，一条库存记录是“仓库中的一个尺码”；在 Ozon 上，它是“一个带有 fbo/fbs 类型数组的商品”；在 Yandex Market 上，它是“仓库 → 商品 → 库存类型（AVAILABLE/FREEZE/DEFECT/…）”。这个服务器将这一切收敛为单一 schema，因此代理可以问“什么快缺货了？”并得到一份覆盖三个账户的答案：

unified stock list: 9 rows from 3 marketplaces
low stock: wildberries/ZR-002=7, ozon/ZR-002=3
ym dual-path stocks ok: 1 FBS (account) + 2 FBO (shop)

这不是示意图——它是 npm test 的输出，该命令让三个适配器全部通过相同的 zod schemas 运行。

第二行如实反映了一个平台怪癖：Yandex Market 将库存拆分到两个 API 方法中，一次调用物理上无法覆盖两种仓库类型。因此，跨三个账户的合并查询只会返回来自 Yandex Market 的卖家仓库，直到代理另外询问 Market 仓库。服务器不会将这一点隐藏在会静默丢弃库存的“便捷”聚合背后。

Related MCP server: Yandex Market Seller MCP Server

无需 API 密钥的快速开始（演示）

无需数据库，无需令牌：没有 DATABASE_URL 时，服务器以内存存储启动，并为全部三个市场提供填充了真实数据的模拟卖家账户。

npm install
npm run dev            # stdio transport

将其连接到 Claude Code：

claude mcp add marketplace -- npx tsx /path/to/marketplace-mcp/src/index.ts

然后在聊天中提问：“显示我的连接”、“什么快缺货了——检查每个市场”、“比较 ZR-002 在三个账户中的价格”、“本周总共有多少订单？”。

连接真实卖家账户

凭据可以来自环境（演示模式，无数据库），也可以加密存储在 PostgreSQL 中（生产模式）。

WB_API_TOKEN=...                          # Wildberries
OZON_CLIENT_ID=... OZON_API_KEY=...       # Ozon
YM_API_KEY=...                            # Yandex Market
npm run dev

每个平台的认证方式都不同，这正是凭据以一组密钥而非单一令牌列存储的原因：

connection_test 会校验密钥，并报告实际可访问的内容：WB 上按 API 类别，Yandex Market 上则列出业务账户和商店。

测试环境

三个市场都不会分发公开的测试凭据——每个沙箱都与卖家账户绑定。实际存在的情况如下：

关于 WB 的一个注意事项已经写进代码：并非每个类别都有沙箱。“Analytics”没有沙箱，而库存正是在该类别中——因此，在沙箱模式下，wb_stocks_get 会与生产 API 通信。服务器不会假装隔离是完整的：sandbox 标志在 connections_list 中可见，marketplace_capabilities 会返回显式的 sandbox_warning。所有操作都是只读的，因此账户永远不会被修改。

生产模式

cp .env.example .env    # MASTER_KEY and MCP_AUTH_TOKEN: openssl rand -hex 32
docker compose up --build

启动 PostgreSQL（自动迁移）以及运行在 Streamable HTTP 上的服务器：POST /mcp，健康检查在 GET /health。

传输安全。 这些工具位于他人的卖家账户密钥之前，因此 /mcp 受 Bearer 令牌（MCP_AUTH_TOKEN）和 Origin 校验（MCP_ALOWED_ORIGINS，DNS 重绑定防御）保护。没有 MCP_AUTH_TOKEN 时，服务器会特意只绑定到 127.0.0.1 并就此发出警告。在 compose 中，端口发布在 loopback 上——请通过 TLS 反向代理暴露它。账户密钥以 AES-256-GCM 密文存储；主密钥位于数据库之外。

架构

MCP client (Claude / ChatGPT / agent)
        │  stdio | Streamable HTTP (stateless, POST /mcp, bearer + Origin)
        ▼
   MCP server ── shared tools: connections_list, connection_test, marketplace_capabilities
        │
        ├─ core: store (Postgres/in-memory) · secrets (AES-GCM) · rate limiter
        │        (token bucket per marketplace+connection+endpoint group) ·
        │        retries (backoff+jitter) · audit (tool_calls) · unified error model
        │
        ├─ adapters/common/schema.ts — THE single normalized schema for all platforms
        │
        ├─ adapters/wb    — Content / Analytics / Statistics / Discounts-Prices APIs
        ├─ adapters/ozon  — Seller API (all methods POST, last_id cursor)
        └─ adapters/ym    — Partner API (businessId → campaignId)

核心原则：

• 每个平台和模拟数据都使用同一个 schema：adapters/common/schema.ts 是唯一事实来源。这些 schema 兼作工具的 outputSchema，因此 SDK 会校验响应，测试套件还会让真实 API 映射通过它们运行。结构漂移会在编译时或测试中失败——而不是在客户的账户中。

• 多账户：当一个市场存在多个连接且未提供 connection_id 时，服务器会返回 AMBIGUOUS_CONNECTION 并附上列表，绝不会静默选择。同样的规则适用于 Yandex Market 业务账户（businessId）。

• FBO 和 FBS 永不合并：在三个平台上，它们都是带有显式 fulfillment_model 的独立行，而非一个混合数字。

• 统一错误模型：AUTH_FAILED、MARKETPLACE_PERMISSION_DENIED、RATE_LIMITED（带 retry_after_ms）、UPSTREAM_TIMEOUT……——带有 retryable 标志的、AI 可读的错误码。

• 金额使用带货币的十进制字符串，日期使用 UTC ISO 8601，分页契约统一为 limit/cursor，覆盖三种不同机制（WB 游标、Ozon last_id、Yandex Market nextPageToken）。

• 机密永远不会被记录，也永远不会出现在响应、错误或审计日志中；只有密文会到达数据库。

工具（17 个）

ym_campaigns_list 之所以存在，是因为 Yandex Market 采用两级模型：业务账户（businessId）包含商店（campaignId），而不同方法需要不同的标识符。

市场 API 合规性（2026-08-28 验证）

路径、主机和限制均对照官方规范校验过，而非凭记忆编写。

Wildberries —— 来自官方 OpenAPI 规范：

• GET /api/v1/supplier/stocks 已于 2026-06-23 停用。 库存现在来自 POST /api/analytics/v1/stocks-report/wb-warehouses（FBO）和 .../seler-warehouses（FBS）；令牌需要“Analytics”类别。

• 新方法不返回卖家货号（只有 nmId），因此 seler_sku 从商品卡片中补充。

• 认证使用不带 Bearer 前缀的原始令牌：规范声明的是 apiKey 安全方案，WB 规范中从未出现 Bearer 一词。

Ozon —— api-sel er.ozon.ru，所有方法都是 POST，使用 last_id 游标分页。使用 /v3/product/list、/v3/product/info/list、/v4/product/info/stocks、/v5/product/info/prices（v4 已弃用）、/v2/posting/fbo/list、/v3/posting/fbs/list。截至 2026 年 8 月，这些接口均无停用通知。Ozon 不发布公开的 OpenAPI 规范，因此该契约是根据文档和受维护客户端汇编而成——这是最需要用真实密钥验证的部分。已在线验证：Ozon 对错误凭据返回 HTTP 400（code: 5 / code: 16）而非 401，客户端会将其映射为 AUTH_FAILED。

Yandex Market —— api.partner.market.yandex.ru，来自官方 OpenAPI 规范（github.com/yandex-mark et/yandex-mark et-partner-api）。限制取自规范：GET /v2/campaigns 1000/小时，POST /v3/businesses/{id}/offers/stocks 500/分钟，POST /v1/businesses/{id}/orders 10000/小时（每个响应最多 50 个订单，窗口 ≤30 天）。非标准的 420 状态被视为速率限制。

Yandex Market 将库存拆分到两个方法中，适配器对此做了处理：POST /v3/businesses/{id}/offers/stocks 覆盖卖家仓库（FBS/DBS/Express，且仅在不存在仓库组时有效），而 POST /v2/campaigns/{campaignId}/offers/stocks 覆盖 Market 仓库（FBY → FBO），并且在存在仓库组时是唯一可行的路径。ym_stocks_get 根据是否传入了 campaign_id 选择正确的路径；要查看全部库存，需要调用该工具两次——这一点在其描述中已向代理明确说明。

尚未验证的部分。 三个平台的实际响应体：规范描述了契约，但只有真实密钥才能确认生产环境在每个字段上都一致——为此计划基于录制响应做契约测试。Ozon 是最薄弱的环节（没有公开规范）。另外，v0.3 特意将以下内容排除在范围外：Ozon 商品品牌（位于属性中，需要单独调用）以及 Ozon 和 Yandex Market 上的仓库名称（独立目录）——这些字段返回 null，而不是凭空捏造。

路线图

测试

npm test

无外部依赖——一对在内存中相互连接的 MCP client↔server。覆盖：tools/list、全部 12 个数据工具均具备 outputSchema、三个平台的模拟数据、分页、FBO/FBS 分离、统一错误模型、审计、响应中不含密钥、跨市场规范化（3 个平台 × 4 种实体类型，共用同一套 schema）、将三个账户的库存合并为一个列表、Yandex Market 的两条库存路径（账户 FBS 与店铺 FBO）、WB sandbox 主机路由（包括没有 sandbox 的类目）、WB / Ozon / Yandex Market 到共享 schema 的真实 API 映射，以及速率限制器行为。

模拟商品标题与仓库名称有意保留为俄语：真实市场平台 API 返回的就是俄语，因此演示能与生产数据保持一致。

许可证

MIT