OZON MCP Server

中文 | English

---

中文文档

OZON MCP Server 是一个基于 Model Context Protocol (MCP) 的工具，通过 Playwright 实现 OZON 电商后台自动化操作，支持 QQ 邮箱验证码自动读取。

功能

• 自动登录 (login-with-email-code) - 使用 QQ 邮箱验证码自动登录 OZON 卖家后台
• 价格监控 (get-marketing-actions) - 获取营销活动商品价格数据，识别低于最低价格的商品
• CLI 直接调用 - 无需 MCP 协议，可从命令行直接执行单个操作

安装

方式一：从 PyPI 安装（推荐）

# 安装 uv (如果没有)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 全局安装 ozon-mcp
uv tool install ozon-mcp

# 安装浏览器
uv tool run ozon-mcp playwright install chromium

方式二：克隆源码开发

# 克隆项目
git clone https://github.com/oychao1988/ozon-mcp.git
cd ozon-mcp

# 安装 uv (如果没有)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync
uv run playwright install chromium

配置环境变量

复制 .env.example 为 .env 并填写：

cp .env.example .env

编辑 .env 文件：

# OZON 账号配置（只需要用户名）
ozon_username="your_qq@qq.com"

# QQ 邮箱授权码（16位）- 获取方式见下方
qq_imap_auth_code="your_16_digit_auth_code"

# Chrome Profile 配置（可选）
chrome_profile_source="copy_to_local"

获取 QQ 邮箱授权码

1. 登录 mail.qq.com
2. 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启 IMAP/SMTP 服务，获取 16 位授权码

在 Claude Code 中配置

方式一：使用已安装的 ozon-mcp 命令（推荐）

claude mcp add ozon --transport stdio -- ozon-mcp

方式二：使用 uvx 远程运行

claude mcp add ozon --transport stdio -- uvx ozon-mcp

使用 uvx 从 GitHub 直接运行（无需安装）

claude mcp add ozon --transport stdio -- uvx github:oychao1988/ozon-mcp

Claude Code 使用示例

配置完成后，可以在 Claude Code 中直接调用 MCP 工具：

# 登录 OZON 账号
使用 ozon 工具执行 login-with-email-code 命令

# 获取营销活动价格数据
使用 ozon 工具执行 get-marketing-actions 命令，参数为 page=1, page_size=20

在 Claude Code 对话中可以这样交互：

# 登录示例
User: 请帮我登录 OZON 卖家后台
Claude: [调用 login-with-email-code]

# 获取数据示例
User: 获取第1页的营销活动商品数据
Claude: [调用 get-marketing-actions，参数 {page: 1, page_size: 20}]

# 获取所有页面数据
User: 获取所有营销活动商品的价格数据
Claude: [调用 get-marketing-actions，参数 {all_pages: true}]

在 Cursor 中配置

在 .mcp.json 或 Cursor MCP 设置中添加：

{
  "mcpServers": {
    "ozon": {
      "command": "ozon-mcp"
    }
  }
}

或使用 uvx：

{
  "mcpServers": {
    "ozon": {
      "command": "uvx",
      "args": ["ozon-mcp"]
    }
  }
}

使用方法

工具列表

1. login-with-email-code

自动登录 OZON 卖家后台（使用 QQ 邮箱接收验证码）。

{
  "command": "login-with-email-code"
}

2. get-marketing-actions

获取营销活动商品价格数据。

{
  "command": "get-marketing-actions",
  "arguments": {
    "page": 1,
    "page_size": 20,
    "all_pages": false
  }
}

参数说明：

参数	类型	默认值	说明
page	number	1	页码（从 1 开始）
page_size	number	20	每页产品数量
all_pages	boolean	false	是否获取所有页面数据

CLI 命令行直接调用

除了通过 MCP 协议在 Claude Code / Cursor 中使用，也可以直接从命令行执行单个操作：

# 检查环境配置
python cli.py check

# 登录 OZON 卖家后台
python cli.py login

# 获取营销活动数据（第1页，50条，表格输出）
python cli.py marketing

# 获取第2页，每页100条
python cli.py marketing --page 2 --page-size 100

# 获取所有页面数据并保存到文件
python cli.py marketing --all --output products.json

# 保存为 CSV 格式
python cli.py marketing --page-size 100 --output data/products.csv

# 无头模式运行（不显示浏览器界面）
python cli.py --headless marketing

# JSON 格式输出（适合管道处理）
python cli.py marketing --json
python cli.py login --json

CLI 参数说明：

命令	参数	说明
check	-	检查环境配置是否完整
login	--headless	无头模式运行
marketing	--page N	页码（从1开始）
	--page-size N	每页产品数量（默认50）
	--all	获取所有页面
	--max-scrolls N	最大滚动次数
	--scroll-delay N	滚动延迟（秒，默认3秒）
	--output PATH	输出文件路径（csv 或 json 格式）
通用	--headless	无头模式
	--json	JSON 格式输出

说明: CLI 脚本直接调用 server.py 中的 handler 函数，复用了全部浏览器自动化逻辑，只是跳过了 MCP 协议层。

运行测试

# 运行所有测试
uv run pytest tests/ -v

# 运行特定测试文件
uv run pytest tests/test_server.py -v

# 运行带覆盖率报告的测试
uv run pytest tests/ -v --cov=ozon_mcp

# 运行特定测试类
uv run pytest tests/test_handlers.py::TestRetryDecorator -v

# 运行特定测试用例
uv run pytest tests/test_server.py::TestLoginOTPFlow::test_otp_filled_then_submit_button_clicked -v

项目结构

ozon-mcp/
├── src/ozon_mcp/          # 核心代码
│   ├── __init__.py        # 版本声明和导出
│   ├── server.py          # MCP Server 入口 + 业务逻辑
│   ├── browser.py         # Playwright 浏览器管理
│   ├── mail.py            # QQ 邮箱 IMAP 操作
│   ├── session.py         # 多账号会话管理
│   ├── _selectors.py      # YAML 选择器加载器
│   ├── selectors.yaml     # 选择器配置文件
│   ├── handlers/          # 工具处理器
│   │   ├── __init__.py
│   │   └── base.py        # BaseHandler 基类
│   └── ozon_selectors.py  # OZON 页面选择器常量
├── cli.py                 # CLI 命令行脚本（直接调用 handler）
├── tests/                 # 测试代码
│   ├── test_browser.py    # 浏览器管理器测试
│   ├── test_handlers.py   # 处理器测试
│   ├── test_mail.py       # 邮箱模块测试
│   ├── test_selectors.py  # 选择器配置测试
│   ├── test_server.py     # MCP Server 测试
│   └── test_session.py    # 会话管理器测试
├── .env.example           # 环境变量示例
├── pyproject.toml         # 项目配置
└── README.md             # 使用说明

发布到 PyPI

# 构建包
uv build

# 发布到 PyPI（需要账号）
uv publish

# 或发布到 TestPyPI 测试
uv publish --repository testpypi

注意事项

1. 隐私保护 - 请勿提交 .env 文件或 chrome-profile/ 目录到 Git
2. 验证码 - 确保 QQ 邮箱能正常接收 OZON 的验证码邮件
3. Chrome Profile - 首次登录后会保存登录状态，避免重复验证

Claude Code 管理命令

# 查看已配置的 MCP 服务器
claude mcp list

# 移除 MCP 服务器
claude mcp remove ozon

# 重新添加（更新版本后）
claude mcp add ozon --transport stdio -- ozon-mcp

# 检查 MCP 服务器状态
claude mcp start ozon

常见问题

Q: 登录失败，显示验证码错误 A: 确保 QQ 邮箱能收到 OZON 的邮件，检查垃圾邮件文件夹

Q: 页面加载超时 A: 增加网络超时时间，或检查 Chrome Profile 是否正常

Q: 如何查看详细日志 A: 运行 RUST_LOG=debug claude 启动 Claude Code 查看 MCP 通信日志

更新日志

v0.1.2 (2026-04-20)

Bug 修复：

• 修复 __version__ 与 pyproject.toml 版本不一致的问题
• 修复 OTP 验证码填写后未点击提交按钮的问题
• 删除重复的 scroll_to_load 函数定义

健壮性改进：

• 添加 tenacity 依赖用于重试逻辑
• IMAP 连接添加 30 秒 socket 超时
• 邮件轮询添加指数退避策略
• 分页失败时返回已获取的部分数据
• scroll_to_load 支持通过 max_scrolls 和 scroll_delay 参数配置

可扩展性改进：

• 新增 SessionManager 支持多账号管理
• 新增 BaseHandler 基类，集成重试和错误恢复逻辑
• Selectors 配置迁移到 YAML 文件，支持热重载
• Server.py 全面采用 SelectorConfig 管理选择器

包修复：

• 修复 pyproject.toml 缺少 handlers 子包和 selectors.yaml 数据文件的打包配置

v0.1.0 (2026-04-20)

初始版本发布，包含：

• login-with-email-code - QQ 邮箱验证码自动登录
• get-marketing-actions - 营销活动价格数据获取
• Playwright 浏览器自动化
• Chrome Profile 会话管理

---

English Docs

OZON MCP Server is a Model Context Protocol (MCP) based tool for automating OZON seller platform operations using Playwright, with QQ Mail OTP support.

Features

• Auto Login - Login to OZON using QQ Mail verification codes
• Price Monitoring - Check marketing action prices and identify underpriced items

Installation

# Install via uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install ozon-mcp

# Install browser
uv tool run ozon-mcp playwright install chromium

Configuration

Copy .env.example to .env and configure:

ozon_username="your_qq@qq.com"
qq_imap_auth_code="your_16_digit_auth_code"

Get QQ Mail auth code from: mail.qq.com → Settings → Account → IMAP/SMTP service

Claude Code Configuration

claude mcp add ozon --transport stdio -- ozon-mcp

Cursor Configuration

Add to .mcp.json or Cursor MCP settings:

{
  "mcpServers": {
    "ozon": {
      "command": "ozon-mcp"
    }
  }
}

License

MIT License - see LICENSE file