AI导哈

电商管理服务器

Ozon Seller MCP Server是一个为俄罗斯最大电商平台Ozon提供AI助手的模型上下文协议服务器，支持产品、订单、定价和分析管理。

  • by MASTER116
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 MASTER116/ozon-mcp-server

使用说明

Ozon卖家MCP服务器

Ozon卖方API的第一个模型上下文协议服务器 --使Claude和Cursor等人工智能助手能够在俄罗斯最大的电子商务市场上管理产品、订单、定价和分析。

英语 | 俄语

为什么这个项目

奥松 是俄罗斯最大的电子商务市场（与亚马逊相当）——纳斯达克上市（OZON），5000多万活跃买家，年GMV超过6亿卢布。成千上万的卖家依赖Ozon卖家API进行库存、定价和订单管理。

Ozon没有MCP服务器。 该项目填补了这一空白，使人工智能助手能够通过标准化的方式直接管理Ozon卖家的运营 模型上下文协议.

为什么重要： 这是一个生产级集成，将俄罗斯电子商务基础设施与全球人工智能工具生态系统连接起来，展示了安全第一的API设计、异步Python架构和全面的OWASP MCP Top 10合规性。

建筑

flowchart TB
    subgraph MCP Clients
        A[Claude Desktop]
        B[Cursor IDE]
        C[Custom Client]
    end

    subgraph MCP Server
        D[FastMCP 2.x<br/>Streamable HTTP / stdio]
        E[Bearer Auth]
        F[Rate Limiter<br/>Token Bucket]
        G[Circuit Breaker]
        H[Input Validation<br/>Pydantic v2]
        I[Audit Logger]
    end

    subgraph Tools — 13 MCP Tools
        J[Products<br/>list · info · create · archive · stocks]
        K[Orders<br/>FBS · FBO]
        L[Analytics<br/>sales · finance]
        M[Warehouses<br/>list]
        N[Pricing<br/>update prices · update stocks]
    end

    subgraph Infrastructure
        O[(PostgreSQL<br/>Audit Logs)]
        P[(Redis<br/>Cache + Rate Limits)]
    end

    Q[Ozon Seller API<br/>api-seller.ozon.ru]

    A & B & C -->|MCP Protocol| D
    D --> E --> F --> G --> H --> I
    I --> J & K & L & M & N
    J & K & L & M & N --> Q
    I --> O
    F --> P
    J & K & L & M & N -.->|cache| P

主要特点

  • 13 MCP工具 --产品CRUD、订单跟踪（FBS/FBO）、销售分析、财务报告、仓库管理、批量定价和库存更新
  • 6层安全架构 --SSRF预防、输入验证、凭证屏蔽、速率限制、审计日志、断路器
  • OWASP MCP十大合规性 --每一个风险 OWASP MCP Top 10（v0.1） 已解决
  • Redis缓存 --基于类别的缓存，具有可配置的TTL，写操作时自动失效
  • PostgreSQL审计日志 --每个工具调用都记录了参数、响应时间和Ozon跟踪ID
  • 断路器 -连续故障后自动关闭Ozon API，并进行恢复探测
  • 生产Docker设置 --多阶段构建、非root用户、只读文件系统、健康检查

快速开始

# Clone the repository
git clone https://github.com/MASTER116/ozon-mcp-server.git
cd ozon-mcp-server

# Configure environment
cp .env.example .env
# Edit .env — set OZON_CLIENT_ID, OZON_API_KEY (from seller dashboard)
# and POSTGRES_PASSWORD (required, no default)

# Start with Docker Compose (includes Redis + PostgreSQL)
docker compose up -d

# Or run locally with uv
uv sync --dev
uv run python -m ozon_mcp_server

注： 存储库中不存储密码或机密。所有凭据必须通过以下方式提供 .env 文件（位于 .gitignore 从未承诺）。

演示模式（不需要Ozon API密钥）

使用真实的模拟数据尝试所有13个工具——不需要Ozon卖家帐户、Redis或PostgreSQL：

DEMO_MODE=true uv run python -m ozon_mcp_server

演示包括5种产品（AirPods、Dyson、JBL、Nike、Samsonite）、4个城市的4个订单、3个仓库、销售分析（210万卢布/150个订单）和财务报告。

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "ozon": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/ozon-mcp-server/docker-compose.yml", "run", "--rm", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your-client-id",
        "OZON_API_KEY": "your-api-key"
      }
    }
  }
}

可用工具

工具 类型 描述 Ozon API端点
get_product_list 阅读 使用分页和可见性过滤器列出产品 /v2/product/list
get_product_info 阅读 按ID、SKU或offer_ID获取详细的产品信息 /v2/product/info
get_stock_on_warehouses 阅读 获取所有仓库的库存水平 /v1/product/info/stocks
create_product 编写 创建新产品列表 /v3/product/import
update_prices 写 批量更新产品价格 /v1/product/import/prices
update_stocks 写入 批量更新库存数量 /v2/products/stocks
archive_product 写入 存档产品（从列表中删除） /v1/product/archive
get_fbs_orders 阅读 列出FBS订单（卖方履行≈FBM） /v3/posting/fbs/list
get_fbo_orders 阅读 列出FBO订单（Ozon≈FBA履行） /v2/posting/fbo/list
get_analytics 阅读 销售分析（收入、订单、浏览量、转化率） /v1/analytics/data
get_finance_report 阅读 金融交易（佣金、罚款） /v3/finance/transaction/list
get_warehouse_list 阅读 列出所有卖家仓库 /v1/warehouse/list

书写工具带有注释 destructiveHint: true --像Claude Desktop这样的MCP客户端在执行之前会提示确认。

安全

安全是一等公民，遵循 OWASP MCP前10名 框架：

层 保护 实施
认证 具有恒定时间比较的承载令牌 middleware/auth.py
SSRF预防 硬编码的基本URL、私有IP阻止、重定向禁止 api/client.py
输入验证 严格的Pydantic v2模式、Allowlist、长度限制 models/*.py
速率限制 Redis令牌桶——全局、每次写入、每次会话 middleware/rate_limit.py
凭证屏蔽 SecretStr 对于所有机密，正则表达式输出净化 middleware/security.py
审计日志 每个使用掩码参数记录到PostgreSQL的工具调用 db/audit_repo.py
断路器 连续5次Ozon API故障后自动切割 api/client.py

看 安全.md 完整的威胁模型和漏洞报告策略。

架构决策

决策 选择 理由
MCP框架 FastMCP 2.x 最受欢迎的MCP框架，内置工具注释，23K+GitHub之星
HTTP客户端 httpx 本机异步、HTTP/2、超时、重试——Python的惯用选择
缓存 Redis 亚毫秒延迟，令牌桶用于速率限制，TTL支持
审计存储 PostgreSQL ACID合规性，JSONB用于参数，索引用于性能
验证 Pydantic v2 严格模式，FastMCP自动生成JSON模式
非FastAPI FastMCP本机 MCP服务器不是REST API；FastMCP提供本地传输
Python 3.12 最新稳定 模式匹配、性能改进、现代类型

技术栈

Python 3.12 · FastMCP · httpx · Pydantic v2 · asyncpg · Redis · PostgreSQL · Docker · GitHub Actions · structlog · tenacity

生产部署

# 1. Copy and fill production config
cp .env.production.example .env

# Generate strong passwords:
#   openssl rand -base64 32   (for POSTGRES_PASSWORD, REDIS_PASSWORD)
#   openssl rand -hex 32      (for MCP_AUTH_TOKEN)

# 2. Start all services
docker compose -f docker-compose.prod.yml up -d

# 3. Check health
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs ozon-mcp

# 4. Run database backup (manual)
docker compose -f docker-compose.prod.yml --profile maintenance run --rm pg-backup

# 5. Run audit cleanup (manual)
docker compose -f docker-compose.prod.yml --profile maintenance run --rm audit-cleanup

生产安全 （vs dev-docker-compose）：

  • 零硬编码密码 --所有秘密通过 .env （从未使用过git）
  • 瑞迪斯: requirepass + CONFIG, KEYS, FLUSHDB, FLUSHALL, DEBUG 残疾的
  • PostgreSQL: scram-sha-256 带索引的auth+init脚本
  • 网络隔离 --MCP端口打开 127.0.0.1 仅限内部网络上的DB/Redis
  • 容器硬化 — cap_drop: ALL, no-new-privileges, read_only 文件系统
  • 资源限制 每个容器（CPU+内存）
  • 日志轮转 （最大大小的json文件驱动程序）
  • 审计清理 （保留90天）和 PostgreSQL备份 （维护简介）

看 安全.md 查看完整的生产硬化检查表。

测试

157测试 随着 83%的代码覆盖率 （阈值：80%）：

uv run pytest -v
测试套件 测试 封面
安全（SSRF、注入、凭证） 20 api/client.py, middleware/*, models/*
产品工具（列表、信息、库存、价格、创建、存档） 19 tools/product_tools.py — 98%
订单工具（FBS、FBO、分析、财务、仓库） 14 tools/order_tools.py — 100%
模型验证（产品、订单、通用） 40 models/* — 93–100%
API客户端（SSRF、断路器、错误） 9 api/client.py
缓存（Redis获取/设置/无效） 7 cache/redis_cache.py
中间件（身份验证、速率限制、安全） 17 middleware/* — 81–100%
服务器（AppContext、MCP实例、资源） 5 server.py

所有的外部依赖（Redis，PostgreSQL，Ozon API）都是完全模拟的-运行测试不需要任何基础设施。

发展

# Install dependencies
uv sync --dev

# Run linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type checking
uv run mypy src/

# Security scanning
uv run bandit -r src/ -c pyproject.toml
uv run pip-audit

# Run tests with coverage
uv run pytest -v

# Pre-commit hooks
uv run pre-commit install

看 贡献.md 获取完整的开发指南。

许可证

麻省理工学院 --阿扎特·哈拉菲耶夫

相关 MCP