marketplace-mcp
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 |
| 卖家后台 → 设置 → API 访问 |
Ozon | 两个请求头: | 卖家后台 → 设置 → 卖家 API |
Yandex Market |
| 卖家后台 → API 模块 → 授权令牌 |
connection_test 会校验密钥,并报告实际可访问的内容:WB 上按 API 类别,Yandex Market 上则列出业务账户和商店。
测试环境
三个市场都不会分发公开的测试凭据——每个沙箱都与卖家账户绑定。实际存在的情况如下:
市场 | 沙箱 | 如何进入 |
Wildberries | 有 —— 独立的 | 沙箱令牌在卖家后台单独创建,与生产令牌分开。通过 |
Ozon | 有 —— 测试环境镜像 Seller API 方法,并与真实数据隔离 | 需要卖家后台的 Client-Id 和 Api-Key |
Yandex Market | 没有独立环境 —— 而是在真实后台中提供测试订单(以 | 卖家后台 → 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 游标、Ozonlast_id、Yandex MarketnextPageToken)。机密永远不会被记录,也永远不会出现在响应、错误或审计日志中;只有密文会到达数据库。
工具(17 个)
工具 | 用途 |
| 已连接的卖家账户,绝不包含机密 |
| 密钥检查:WB 上按 API 类别,Yandex Market 上显示商店列表 |
| 代理可以访问什么,需要哪些凭据和权限范围 |
| Wildberries |
| Ozon |
| Yandex Market |
ym_campaigns_list 之所以存在,是因为 Yandex Market 采用两级模型:业务账户(businessId)包含商店(campaignId),而不同方法需要不同的标识符。
市场 API 合规性(2026-08-28 验证)
路径、主机和限制均对照官方规范校验过,而非凭记忆编写。
Wildberries —— 来自官方 OpenAPI 规范:
分组 | 主机 | 限制 |
Content |
| 100/min |
Prices and discounts |
| 10/6s |
Statistics |
| 1/min |
Analytics |
| 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 toolsconnection_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
Scored across 17 tools
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.
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.
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.
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
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Real-time Amazon product, seller, and search data for AI agents across 22 marketplaces.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Russian APIs for AI agents: YooKassa, CDEK, Bitrix24 and more. Ready scenarios with code. No key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Wildberries and Ozon seller accounts for real-time access to sales, stocks, prices, finances, and reviews through official APIs.MIT
- AlicenseAqualityCmaintenanceEnables 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.12MIT
- AlicenseAqualityBmaintenanceWildberries 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.2561 PyPI5MIT
- AlicenseNot gradedqualityBmaintenanceLets 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