Skip to main content
Glama
marketplace-mcp

marketplace-mcp

by bssoft2b

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: WB Readonly MCP

无需 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

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

市场

认证方式

获取位置

Wildberries

Authorization: <token> 请求头(没有 Bearer 前缀)

卖家后台 → 设置 → API 访问

Ozon

两个请求头:Client-Id + Api-Key

卖家后台 → 设置 → 卖家 API

Yandex Market

Api-Key: <key> 请求头

卖家后台 → API 模块 → 授权令牌

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

测试环境

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

市场

沙箱

如何进入

Wildberries

有 —— 独立的 *-api-sandbox.wildberries.ru 主机,带生成的测试数据

沙箱令牌在卖家后台单独创建,与生产令牌分开。通过 WB_SANDBOX=1 支持

Ozon

有 —— 测试环境镜像 Seller API 方法,并与真实数据隔离

需要卖家后台的 Client-Id 和 Api-Key

Yandex Market

没有独立环境 —— 而是在真实后台中提供测试订单(以 fake: true 交付)

卖家后台 → API 模块 → 测试订单

关于 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 个)

工具

用途

connections_list / connection_get

已连接的卖家账户,绝不包含机密

connection_test

密钥检查:WB 上按 API 类别,Yandex Market 上显示商店列表

marketplace_capabilities

代理可以访问什么,需要哪些凭据和权限范围

wb_products_list · wb_stocks_get · wb_prices_get · wb_orders_list

Wildberries

ozon_products_list · ozon_stocks_get · ozon_prices_get · ozon_orders_list

Ozon

ym_campaigns_list · ym_products_list · ym_stocks_get · ym_prices_get · ym_orders_list

Yandex Market

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

市场 API 合规性(2026-08-28 验证)

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

Wildberries —— 来自官方 OpenAPI 规范:

分组

主机

限制

Content

content-api.wildberries.ru

100/min

Prices and discounts

discounts-prices-api.wildberries.ru

10/6s

Statistics

statistics-api.wildberries.ru

1/min

Analytics

seller-analytics-api.wildberries.ru

3/min

  • 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,而不是凭空捏造。

路线图

阶段

范围

状态

1. 核心

连接、密钥、权限、审计、速率限制、错误模型

✅

2. Wildberries 读取

商品 / 库存 / 价格 / 订单

✅

3. Ozon 读取

Seller API:商品 / 库存 / 价格 / 订单 FBO+FBS

✅

4. Yandex Market 读取

店铺 / 商品 / 库存 / 价格 / 订单

✅

4b. 扩展读取

财务、评价、广告(Ozon Performance API、WB Advert)

—

5. 历史数据收集器

价格/库存快照工作者(相关表已存在于 schema 中)

—

6–7. 写入

预览/试运行 → 确认 → 执行;策略限制;幂等性

—

测试

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

Available Tools

17 tools
connection_getGet connectionA

Returns details of a single connection by connection_id (never secrets).

Inputs: connection_id (required).

connections_listList connectionsA

Returns every connected marketplace seller account (never keys or secrets). Call this first to learn the connection_id required by the other tools.

Inputs: no named parameters.

connection_testTest connectionB

Performs a real read-only connectivity check: token validity and API availability. The seller account is not modified.

Inputs: connection_id (required).

marketplace_capabilitiesConnection capabilitiesA

Shows which data categories are actually available to the AI for this connection (token scopes plus server policy). Call before using the marketplace-specific tools.

Inputs: connection_id (required).

ozon_orders_listOzon: list ordersA

Returns Ozon postings for a period (30 days by default): posting number, date, items, amount, status. FBO and FBS are independent order streams on Ozon; both are returned by default. Read-only.

Inputs: limit, cursor, date_from, connection_id, +1 more. Returns: data, meta, success, marketplace, +1 more

ozon_prices_getOzon: get pricesA

Returns current Ozon prices: price before discount, price for the customer, currency. Read-only; never changes prices. Money values are decimal strings.

Inputs: limit, cursor, connection_id. Returns: data, meta, success, marketplace, +1 more

ozon_products_listOzon: list productsA

Returns Ozon products: product_id, seller article (offer_id), title, category. Read-only. Use it to survey the assortment; do not use it for stocks (ozon_stocks_get) or prices (ozon_prices_get).

Inputs: limit, cursor, connection_id. Returns: data, meta, success, marketplace, +1 more

ozon_stocks_getOzon: get stocksA

Returns Ozon stock levels split by FBO (Ozon warehouses) and FBS (seller warehouses): available to order and reserved. Read-only. Fulfillment models are never merged.

Inputs: limit, cursor, seller_sku, connection_id, +1 more. Returns: data, meta, success, marketplace, +1 more

wb_orders_listWB: list ordersA

Returns Wildberries orders for a period (30 days by default): date, article, amount, warehouse, status. Read-only. WB refreshes this data every 30 minutes and retains it for 90 days. For aggregate sales stats, call this tool and compute on the AI side.

Inputs: limit, cursor, date_from, connection_id. Returns: data, meta, success, marketplace, +1 more

wb_prices_getWB: get pricesA

Returns current Wildberries prices and discounts. Read-only; never changes prices. Money values are decimal strings with a currency, never floats.

Inputs: limit, cursor, connection_id. Returns: data, meta, success, marketplace, +1 more

wb_products_listWB: list productsA

Returns Wildberries product cards: WB article (nmID), seller article, barcode, title, brand, category. Read-only; the seller account is not modified. Use it to survey the assortment; do not use it for stocks (wb_stocks_get) or prices (wb_prices_get).

Inputs: limit, cursor, connection_id. Returns: data, meta, success, marketplace, +1 more

wb_stocks_getWB: get stocksA

Returns current stock levels split by FBO (WB warehouses) and FBS (seller warehouses): available to order, in transit to customer, in transit from customer. Read-only. Fulfillment models are never merged into one number. WB refreshes this data every 30 minutes. Requires the Analytics (Аналитика) token category.

Inputs: seller_sku, connection_id, fulfillment_model, marketplace_product_id. Returns: data, meta, success, marketplace, +1 more

ym_campaigns_listYandex Market: list businesses and shopsA

Returns the Yandex Market shops (campaignId) and business accounts (businessId) the token can reach. Yandex Market has a two-level structure: an account holds several shops, and different methods need different identifiers. Call this before the other ym_* tools.

Inputs: connection_id.

ym_orders_listYandex Market: list ordersA

Returns Yandex Market orders for a period (30 days by default): date, items, amount, status, shop. Read-only. A single request spans at most 30 days (API limitation).

Inputs: limit, cursor, date_from, business_id, +1 more. Returns: data, meta, success, marketplace, +1 more

ym_prices_getYandex Market: get pricesB

Returns Yandex Market prices: base price, price for the customer, currency. Read-only; never changes prices. Money values are decimal strings.

Inputs: limit, cursor, business_id, connection_id. Returns: data, meta, success, marketplace, +1 more

ym_products_listYandex Market: list productsA

Returns Yandex Market products: seller article (offerId), title, category, barcode, Market SKU. Read-only. Operates at the business-account level (businessId), not per shop.

Inputs: limit, cursor, business_id, connection_id. Returns: data, meta, success, marketplace, +1 more

ym_stocks_getYandex Market: get stocksA

Returns Yandex Market stock levels: available to order and reserved. Read-only. Market stock types (AVAILABLE/FIT/FREEZE/DEFECT/…) are normalized: sellable quantity is kept separate from reserved and defective stock. IMPORTANT: Yandex Market splits stocks across two methods and a single call does NOT cover both. Without campaign_id you get seller warehouses (FBS/DBS/Express). With campaign_id you get Market warehouses (FBY, i.e. the FBO model), which is also the only working path for accounts with warehouse groups. To see all stock, call it twice: without campaign_id and with it (shop ids come from ym_campaigns_list).

Inputs: limit, cursor, seller_sku, business_id, +2 more. Returns: data, meta, success, marketplace, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct resource and marketplace: connections, capabilities, products, stocks, prices, and orders are clearly separated, and provider prefixes (wb_/ozon_/ym_) remove cross-marketplace confusion. The descriptions also explicitly warn against using one tool for another data category.

    Naming Consistency4/5

    The naming pattern is largely consistent: provider prefix plus resource plus list/get (e.g., wb_products_list, ozon_stocks_get, ym_orders_list). Minor deviations include connections_list vs connection_get/connection_test (plural/singular inconsistency) and marketplace_capabilities lacking a verb suffix.

    Tool Count4/5

    17 tools is slightly above the typical 3-15 range, but the count is justified by covering three separate marketplaces with four data categories each plus connection and capability tools. No tool feels redundant; the scope is broad but well organized.

    Completeness5/5

    The server fully covers the read-only marketplace domain: products, stocks, prices, and orders for all three supported marketplaces, plus connection discovery, testing, and capability checks. Required prerequiste lookups like ym_campaigns_list are present, so the user has no dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to Wildberries and Ozon seller accounts for real-time access to sales, stocks, prices, finances, and reviews through official APIs.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables read-only analytics and product search for a Wildberries seller account, covering items, advertising, sales, stock, reviews, finances, and tariffs through MCP clients like ChatGPT or Cursor.
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Wildberries seller API in your AI assistant: sales and stocks, product cards, prices and promotions, financial reports and reviews. 307 methods across all 17 Wildberries hosts live in a YAML catalog the server executes, the agent searches it in plain language, and every method carries an access class so writes and irreversible calls ask for confirmation.
      25
      61 PyPI
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets AI agents read and query Wildberries, Ozon, and Yandex Market seller accounts through unified typed tools, with multi-account support, rate limiting, and encrypted credentials.
      MIT