shopee-mcp

MCP-сервер для поиска товаров на Shopee (Сингапур / Индонезия) и получения affiliate-ссылок через официальный Shopee Affiliate Open API.

Инструменты (tools)

shopee_search_products

Поиск товаров по ключевому слову в каталоге Shopee.

sort_type:

• 1 — по релевантности / новинки

• 2 — по продажам (убывание)

• 3 — по цене (возрастание)

• 4 — по цене (убывание)

• 5 — по ставке комиссии (убывание)

Ответ (markdown) — карточки товаров: название, картинка, цена, скидка, рейтинг, число продаж, магазин, ссылка.

Ответ (json):

{
  "keyword": "wireless earbuds",
  "count": 20,
  "page_info": { "page": 1, "limit": 20, "hasNextPage": true },
  "products": [
    {
      "itemId": 123456,
      "productName": "Earbuds Pro X",
      "productLink": "https://shopee.sg/product/123456",
      "offerLink": "https://shope.ee/affiliate-link",
      "imageUrl": "https://...",
      "priceMin": 29.9,
      "priceMax": 39.9,
      "priceDiscountRate": 15,
      "sales": 4821,
      "ratingStar": 4.8,
      "commissionRate": "0.03",
      "shopId": 200001,
      "shopName": "TechStore SG"
    }
  ]
}

shopee_get_buy_link

Генерирует трекаемую affiliate-ссылку для конкретного товара. Покупку пользователь совершает сам, открыв ссылку — сервер ничего не заказывает и не оплачивает.

Ответ (json):

{
  "origin_url": "https://shopee.sg/product/123456",
  "short_link": "https://shope.ee/abc123"
}

Related MCP server: mcp-brazil-marketplaces

Mock-режим

Если переменные SHOPEE_APP_ID / SHOPEE_APP_SECRET не заданы, сервер автоматически возвращает детерминированные тестовые данные. В markdown-ответе появится предупреждение ⚠️ Mock data, в JSON — поле "note".

Это позволяет разрабатывать и тестировать сервер без реального доступа к API.

Установка

git clone https://github.com/TatarchenkovAndrey/shopee-mcp
cd shopee-mcp
python3 -m venv venv
./venv/bin/pip install -e .
cp .env.example .env

Если есть ключи — впишите их в .env:

SHOPEE_APP_ID=your_app_id
SHOPEE_APP_SECRET=your_app_secret

Получение ключей Shopee Affiliate API

1. Подайте заявку на партнёрской странице Shopee:

   • Сингапур: affiliate.shopee.sg

   • Индонезия: портал Shopee ID

   Заявки проверяются вручную — обычно 5–15 дней.

2. После одобрения откройте раздел Open API в личном кабинете партнёра и скопируйте App ID и App Secret.

3. Без ключей сервер работает в mock-режиме.

⚠️ Перед первым реальным вызовом сверьте точный домен эндпоинта и GraphQL-схему с документацией из личного кабинета — они могут незначительно отличаться по стране.

Как устроена аутентификация

Каждый запрос к Shopee API подписывается по схеме:

signature = SHA256(appId + timestamp + payload + appSecret)

Заголовок запроса:

Authorization: SHA256 Credential=<appId>,Timestamp=<ts>,Signature=<sig>

Реализация: src/shopee_mcp/client.py — функция _sign().

Запуск и тест

# Прогнать оба инструмента на mock-данных
PYTHONPATH=src ./venv/bin/python smoke_test.py

Добавление в Claude Code

Локально (stdio)

claude mcp add shopee_mcp -- /полный/путь/к/venv/bin/python -m shopee_mcp.server

Claude Code запустит сервер как дочерний процесс. Работает только на вашей машине.

Удалённо (Streamable HTTP)

Чтобы сервером мог пользоваться любой пользователь Claude Code:

1. Запустите сервер в HTTP-режиме:

   MCP_TRANSPORT=streamable-http PORT=8000 ./venv/bin/python -m shopee_mcp.server

2. Разверните за публичным HTTPS (Fly.io, Render, Railway, VPS + nginx/TLS). Для разработки — ngrok http 8000.

3. Пользователи подключают сервер командой:

   claude mcp add --transport http shopee_mcp https://your-domain/mcp

Переменные окружения

Структура проекта

shopee-mcp/
├── pyproject.toml              # зависимости, точка входа
├── .env.example                # шаблон переменных окружения
├── smoke_test.py               # быстрый тест обоих инструментов
└── src/shopee_mcp/
    ├── __init__.py
    ├── client.py               # подпись запросов, GraphQL API, mock-данные
    ├── formatting.py           # форматирование ответов (markdown / json)
    └── server.py               # FastMCP сервер, Pydantic-схемы, регистрация tools

Важно

Этот сервер не выполняет покупки и не вводит платёжные данные. Он только ищет товары и генерирует affiliate-ссылку — оплату пользователь всегда совершает сам в браузере или приложении Shopee.