sellercloud-mcp

Первый сервер протокола контекста модели (MCP) для SellerCloud. Подключите Claude к своему каталогу, инвентарю, заказам и спискам каналов — только для чтения, за пять минут.

Зачем это нужно

У SellerCloud нет публичного SDK. Их REST API хорошо задокументирован, но не имеет унифицированного интерфейса — каждая команда, автоматизирующая работу с ним, в итоге пишет один и тот же код для аутентификации и пагинации с нуля.

Если вы используете Claude (или любого ИИ-ассистента с поддержкой MCP) для повседневной работы с электронной коммерцией, этот разрыв — разница между тем, чтобы "сделать сводку заказов за сегодня" сразу, и тем, чтобы требовать для этого специальную интеграцию.

sellercloud-mcp устраняет этот разрыв. Это компактный, хорошо протестированный MCP-сервер с лицензией MIT, который предоставляет семь эндпоинтов SellerCloud (только для чтения) любому MCP-клиенту. Создан на основе многолетнего опыта автоматизации электронной коммерции в масштабе.

Related MCP server: Amazon Marketplace MCP Server by CData

Что можно делать с его помощью

Подключите этот сервер к Claude Code, Claude Desktop или любому другому MCP-хосту, а затем задавайте вопросы, например:

• "Найди любой SKU, содержащий WIDGET, и покажи мне уровни запасов."

• "Сколько заказов мы отправили вчера по всем маркетплейсам? Сгруппируй по каналам."

• "Получи заказ 100001 и скажи мне, какие позиции были отправлены."

• "Перечисли каналы, настроенные для компании 9001, и покажи, какие из них активны."

• "Для SKU ACME-001 сравни цену по всем каналам продаж."

Claude читает ваш каталог напрямую. Никакого копирования-вставки, никаких таблиц, никаких пользовательских конвейеров.

Инструменты (v0.1, только для чтения)

Эндпоинты для записи (создание заказа, обновление инвентаря, отправка изменений в каналы) намеренно отсутствуют в v0.1. Они запланированы на v0.2, как только будет отлажена эргономика режима чтения.

Установка

pip install sellercloud-mcp

v0.1 поставляется из этого репозитория. Публикация в PyPI ожидается — пока что устанавливайте через pip install git+https://github.com/alveyautomation/sellercloud-mcp или клонируйте и запустите pip install -e . локально.

Настройка учетных данных

Сервер считывает все данные из переменных окружения. Скопируйте .env.example в .env и заполните данные вашего арендатора:

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

Используйте учетную запись SellerCloud только для чтения. v0.1 вызывает только GET эндпоинты, но эшелонированная защита означает, что вам следует предоставить серверу выделенного пользователя, который не может ничего изменять. Когда выйдет v0.2 с инструментами записи, вы сможете обновить учетные данные — но не наоборот.

Подключение к Claude Code

Добавьте в ~/.claude/claude_code_config.json (или в конфигурацию MCP вашего проекта):

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

Перезапустите Claude Code. Семь инструментов sellercloud_* появятся в любой новой сессии.

Подключение к Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows) и добавьте тот же блок mcpServers, что и выше. Перезапустите настольное приложение.

Справочник инструментов

Каждый инструмент возвращает JSON-конверт:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

Пример ответа:

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

Возвращает запись из каталога или data: null, если SKU отсутствует в каталоге компании.

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

Пагинация обрабатывается прозрачно — SellerCloud ограничивает размер страницы 50 записями, но инструмент собирает страницы до достижения limit. Ответ включает limit_reached: true, если заказов было больше, чем позволяет limit.

sellercloud_get_order

sellercloud_get_order(order_id: int)

Возвращает полную запись заказа (с Items[]) или data: null при ошибке 404.

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

Возвращаемая запись включает:

• InventoryAvailableQty — то, что API считает доступным для продажи прямо сейчас

• PhysicalQty — в наличии

• ReservedQty — зарезервировано для открытых заказов

• OnOrder — количество по входящим заказам на закупку (PO)

Используйте InventoryAvailableQty как каноническое число "количество, которое я могу продать".

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

Возвращает список настроенных фидов каналов для компании. Каждая запись включает ChannelID, Name и Active.

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

Детали листинга по конкретному каналу. Полезно для выборочной проверки цен на маркетплейсах.

Локальная разработка

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

Хуки pre-commit (gitleaks, ruff, форматировщик, очистка отпечатков арендатора):

pip install pre-commit
pre-commit install

Интеграционные тесты с реальной песочницей SellerCloud скрыты за флагом SELLERCLOUD_INTEGRATION_TESTS=1. Они не требуются для обычного участия в разработке.

Устранение неполадок

Failed to obtain SellerCloud token — имя пользователя/пароль отклонены. Самая частая причина: включена двухфакторная аутентификация (2FA) или аккаунт заблокирован. Эндпоинт SellerCloud POST /api/token ожидает сервисную учетную запись без 2FA.

Missing required environment variables — сервер попытался запуститься до того, как был загружен файл .env. Либо экспортируйте переменные в родительской оболочке, либо убедитесь, что конфигурация вашего MCP-хоста включает их в блоке env.

Пустые результаты при наличии данных — убедитесь, что company_id указан верно. SellerCloud возвращает данные только по основной компании аутентифицированного пользователя, если вы явно не передадите companyID.

Пагинация кажется медленной — размер страницы ограничен 50 записями со стороны SellerCloud, а не нами. Для больших временных интервалов ожидайте несколько запросов.

Участие в разработке

Приветствуются сообщения об ошибках и pull-реквесты. Пожалуйста:

• Запустите pytest перед открытием PR (pip install -e ".[dev]").

• Запустите pre-commit run --all-files.

• Ограничьте дополнения для v0.1 только режимом чтения. Эндпоинты для записи появятся в v0.2.

• Используйте только синтетические данные в тестах — никаких реальных SKU, имен клиентов или номеров заказов.

Лицензия

MIT — см. LICENSE.

Отказ от ответственности

sellercloud-mcp — это неофициальная сторонняя интеграция. Она не одобрена, не аффилирована и не поддерживается SellerCloud, Inc. "SellerCloud" является торговой маркой SellerCloud, Inc. Используйте на свой страх и риск; проверяйте поведение на своем арендаторе, прежде чем полагаться на него при принятии производственных решений.