Skip to main content
Glama
deenesjakoruzh
oychao1988

OZON MCP Server

by oychao1988
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

OZON MCP Server

Python 3.10+ License: MIT PyPI version

中文 | 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 会话管理

Related MCP server: Browser Testing MCP Server

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

Available Tools

2 tools
get-marketing-actionsB

获取营销活动数据（产品名称、SKU、当前价格、最低价）

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo页码（从 1 开始）
page_sizeNo每页产品数量
all_pagesNo是否获取所有页面数据
max_scrollsNo滚动加载最大次数
scroll_delayNo每次滚动之间的等待时间（秒）

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behaviors. It does not mention that the tool is read-only, rate limits, side effects, or pagination behavior despite 5 parameters controlling scrolling and pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the core purpose. It is efficient but could benefit from additional details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description partially explains return data but lacks details on structure, pagination, or limitations. With 5 parameters, more context is needed for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value by listing returned fields (product name, SKU, price), which gives context but does not elaborate on individual parameters beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves marketing campaign data and lists specific fields (product name, SKU, current price, lowest price). It distinguishes from the sibling tool 'login-with-email-code' which is for authentication.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for fetching marketing data but provides no explicit guidance on when to use it versus alternatives. No when-not or context is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

login-with-email-codeB

登录 OZON 卖家后台，使用 QQ 邮箱接收验证码

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description only states the action; no mention of behavioral traits like error handling, rate limits, session management, or what happens with invalid codes. With no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, appropriately concise and front-loaded. Could be slightly more structured but not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a login tool with no output schema and no annotations, the description lacks completeness. It does not explain how the verification code works, prerequisites, or expected outcomes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has no parameters, so description does not need to add meaning. Baseline score of 4 for empty params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool logs into OZON seller backend using QQ email verification code. It is a specific verb+resource and distinguishes from the sibling 'get-marketing-actions'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs the sibling. No when-not or alternative context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

The two tools serve entirely different purposes: one handles authentication and the other retrieves marketing data. There is no functional overlap, making it trivial for an agent to distinguish between them.

Naming Consistency4/5

Both tool names use hyphens and follow a verb-noun structure. However, one uses 'get' with a noun phrase while the other uses 'login' with a prepositional phrase, which is a minor inconsistency in verb pattern.

Tool Count2/5

With only two tools, the server feels underpopulated for its apparent scope as an OZON seller platform. Most servers in this domain would require a dozen or more tools to cover basic operations.

Completeness1/5

The server severely lacks expected functionality. After logging in, users would need tools for products, orders, campaigns, and more. A single data retrieval tool leaves massive gaps in the tool surface.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oychao1988/ozon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server