Skip to main content
Glama
deenesjakoruzh
oychao1988

OZON MCP Server

by oychao1988
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

OZON MCP 서버

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 프로토콜 없이 명령줄에서 직접 단일 작업 실행 가능

설치

방법 1: 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

방법 2: 소스 코드 복제 및 개발

# 克隆项目
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 설정

방법 1: 설치된 ozon-mcp 명령 사용 (권장)

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

방법 2: 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의 핸들러 함수를 직접 호출하며, 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)

버그 수정:

  • __version__과 pyproject.toml 버전이 일치하지 않는 문제 수정

  • OTP 인증 코드 입력 후 제출 버튼을 클릭하지 않는 문제 수정

  • 중복된 scroll_to_load 함수 정의 삭제

견고성 개선:

  • 재시도 로직을 위해 tenacity 의존성 추가

  • IMAP 연결에 30초 소켓 타임아웃 추가

  • 메일 폴링에 지수 백오프 전략 추가

  • 페이지네이션 실패 시 이미 가져온 부분 데이터 반환

  • 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는 Model Context Protocol (MCP) 기반의 도구로, Playwright를 사용하여 OZON 판매자 플랫폼 운영을 자동화하며 QQ 메일 OTP를 지원합니다.

기능

  • 자동 로그인 - QQ 메일 인증 코드를 사용하여 OZON에 로그인

  • 가격 모니터링 - 마케팅 활동 가격을 확인하고 저가 상품 식별

설치

# 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

설정

.env.example을 .env로 복사하고 설정하세요:

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

QQ 메일 인증 코드는 mail.qq.com → 설정 → 계정 → IMAP/SMTP 서비스에서 획득 가능합니다.

Claude Code 설정

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

Cursor 설정

.mcp.json 또는 Cursor MCP 설정에 추가:

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

라이선스

MIT 라이선스 - LICENSE 파일 참조

Install Server
A
license - permissive license
B
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • chromedevtoolsmcp-mcp

    A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,

  • agentcentral

    Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.

  • DataDoe MCP

    Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

View all MCP Connectors

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