MCP-сервер Cin7 Omni

Сервер MCP, который предоставляет Claude полный доступ к Cin7 Omni API — всем ресурсам и всем операциям, которые поддерживает API:

Contacts · Branches · Product Categories · Products · Product Options · Product Images · Size Ranges · Stock · Serial Numbers · Branch Transfers · Adjustments · Vouchers · Sales Orders (incl. cartons) · Payments · Payment Fees & Payouts · Purchase Orders · Quotes · Credit Notes · BOM Masters (v1 & v2) · Production Jobs · Users · Cartons

Матрица глаголов (какие ресурсы можно получать списком, получать по одному, создавать, обновлять или удалять) взята из официальной swagger-спецификации Cin7 и соблюдается сервером, поэтому Claude никогда не сможет выполнить операцию, которую API не поддерживает.

Инструменты

Чтение и запись реализованы отдельными инструментами с соответствующими MCP-аннотациями (readOnlyHint, destructiveHint), поэтому в Claude вы можете задать для каждого инструмента записи Always allow, Ask each time или Deny независимо от инструментов чтения.

Related MCP server: BILLZ MCP Bridge Server

Установка в Claude Desktop (3 шага, без редактирования конфигурации)

1. Получите учётные данные Cin7 API — в Cin7 Omni: Settings (⚙) → Integrations → API v1 → Add API Connection. Это даст вам API Username и API Key (учётные данные Basic-auth, а не ваш вход в Cin7). Выдайте подключению разрешение на модули, к которым должен обращаться Claude, — модуль без разрешения вернёт 403.

2. Скачайте dist/cin7-omni.mcpb — один файл, ~150 KB.

3. Откройте его — дважды щёлкните файл (или в Claude Desktop: Settings → Extensions → перетащите файл в окно) и нажмите Install. При запросе вставьте API Username и API Key; ключ хранится в связке ключей вашего компьютера и никогда не сохраняется в файле. Кроме того, есть переключатель Read-only mode, если вы хотите, чтобы Claude был ограничен только просмотром.

Затем попросите Claude что-нибудь вроде "describe the Cin7 SalesOrders resource", чтобы убедиться, что всё работает.

Чтобы удалить его позже: Claude Desktop → Settings → Extensions → Cin7 Omni → Uninstall.

Другие способы запуска

В репозитории также поставляется готовый автономный сервер (dist/index.js — все зависимости включены в бандл), так что для запуска достаточно клонировать репозиторий: не нужен ни npm install, ни этап сборки. git pull всегда даёт вам последнюю готовую к тестированию сборку.

git clone https://github.com/panagiotis1226/cin7-omni-mcp.git

Только если вы сами правите исходный код: npm install (при этом выполняется автоматическая сборка) или npm run build для пересборки.

Claude Code:

claude mcp add cin7-omni \
  -e CIN7_API_USERNAME=YourApiUsername \
  -e CIN7_API_KEY=your-api-key \
  -- node /absolute/path/to/cin7-omni-mcp/dist/index.js

Claude Desktop (ручная настройка) — добавьте в claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "cin7-omni": {
      "command": "node",
      "args": ["/absolute/path/to/cin7-omni-mcp/dist/index.js"],
      "env": {
        "CIN7_API_USERNAME": "YourApiUsername",
        "CIN7_API_KEY": "your-api-key"
      }
    }
  }
}

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

Управление доступом на запись

Два уровня:

1. Разрешения Claude для каждого инструмента — когда Claude впервые вызывает cin7_create, cin7_update, cin7_delete или cin7_upload_product_image, вы получите запрос и сможете выбрать allow once, always allow или deny для каждого инструмента (в Claude Code управляйте ими в разделе /permissions).

2. Жёсткая блокировка на стороне сервера — установите CIN7_READ_ONLY=true, и инструменты записи не будут зарегистрированы вовсе.

Лимиты запросов

Cin7 ограничивает запросы: 3 вызова в секунду, 60 в минуту, 5000 в день. Сервер ставит запросы в очередь на стороне клиента, чтобы не превышать посекундные/поминутные лимиты, и автоматически повторяет запросы при ответах 429/5xx с увеличением задержки (backoff), поэтому большие многостраничные выгрузки по замыслу выполняются медленно. Используйте фильтры where (например, modifiedDate>='...') и параметр fields, чтобы минимизировать число запросов.

Примеры запросов

• "Сколько остатков CTS001 у нас по филиалам?" → cin7_list по ресурсу Stock с where: "code='CTS001'"

• "Покажи заказы на продажу, отправленные на этой неделе, на сумму более $500" → cin7_list по ресурсу SalesOrders с фильтром where

• "Создай заказ на закупку для поставщика X со следующими позициями…" → cin7_describe PurchaseOrders, затем cin7_create

• "Какие поля есть у Contact?" → cin7_describe Contacts

Разработка

npm test           # builds, then runs the stdio smoke test against a mock Cin7 API
npm run build:mcpb # rebuild + validate manifest + repack dist/cin7-omni.mcpb
npm run dev        # run from source with tsx

Сборка создаёт два бандла из одного исходного кода: dist/index.js (ESM, для запуска после клонирования / Claude Code) и server/index.cjs (CJS, упаковывается в расширение .mcpb).

src/fieldReference.ts создаётся из официальной swagger-спецификации Cin7 скриптом scripts/gen_fields.py (ожидает swagger.json с https://api.cin7.com/api/swagger/v1/swagger.json в рабочем каталоге) — перегенерируйте, если Cin7 обновит свой API.

Что не охвачено

• Вебхуки Cin7 Omni (push-уведомления) — этот сервер работает только в режиме запрос/ответ.

• Всё, что Cin7 не предоставляет через API v1/v2.

• Удалённое/HTTP-развёртывание — это локальный stdio-сервер; позже можно будет добавить точку входа streamable-HTTP.