Cin7 Omni MCP Server

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 (カートンを含む) · Payments · Payment Fees & Payouts · Purchase Orders · Quotes · Credit Notes · BOM Masters (v1 & v2) · Production Jobs · Users · Cartons

動詞マトリックス(どのリソースを一覧表示、取得、作成、更新、削除できるか)は、Cin7 の公式 swagger 仕様から取得され、サーバー側で強制されます。そのため、Claude が API がサポートしていない操作を試みることは決してありません。

ツール

読み取りと書き込みは、適切な MCP アノテーション(readOnlyHint、destructiveHint)を備えた別々のツールです。そのため Claude では、各書き込みツールを読み取りツールとは独立に、常に許可、毎回確認、拒否 のいずれかに設定できます。

Related MCP server: GHL MCP Server

Claude Desktop へのインストール(3 ステップ、設定ファイルの編集は不要)

1. Cin7 API の認証情報を取得 — Cin7 Omni で:設定 (⚙) → 統合 → API v1 → API 接続を追加。これで API Username と API Key が発行されます(Basic 認証の認証情報であり、Cin7 のログイン情報ではありません)。Claude にアクセスさせたいモジュールへの権限をこの接続に付与してください — 権限のないモジュールは 403 を返します。

2. ダウンロード dist/cin7-omni.mcpb — 1 つのファイル、約 150 KB。

3. 開く — ファイルをダブルクリックするか(または Claude Desktop で:設定 → 拡張機能 → ファイルをドラッグ&ドロップ)、インストール をクリックします。プロンプトが表示されたら API Username と API Key を貼り付けます。キーはお使いのコンピュータのキーチェーンに保存され、ファイルに保存されることは決してありません。Claude を参照のみに制限したい場合は、読み取り専用モード のトグルもあります。

その後、Claude に 「Cin7 SalesOrders リソースを説明してください」 のような依頼をして、動作することを確認してください。

後で削除するには:Claude Desktop → 設定 → 拡張機能 → Cin7 Omni → アンインストール。

その他の実行方法

プリビルド済みの自己完結型サーバーもリポジトリに同梱されています(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 に追加します(設定 → 開発者 → 設定を編集):

{
  "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"
      }
    }
  }
}

環境変数

書き込みアクセスの制御

2 つのレイヤー:

1. Claude のツールごとの権限 — Claude が初めて cin7_create、cin7_update、cin7_delete、cin7_upload_product_image のいずれかを呼び出すと、プロンプトが表示され、ツールごとに 1 回だけ許可、常に許可、拒否 を選択できます(Claude Code では /permissions で管理します)。

2. サーバー側のハードロック — CIN7_READ_ONLY=true を設定すると、書き込みツールは一切登録されません。

レート制限

Cin7 は 3 コール/秒、60 コール/分、5,000 コール/日 を強制します。サーバーは毎秒/毎分の制限内に収まるようリクエストをクライアント側でキューに入れ、429/5xx ではバックオフ付きで自動リトライします。そのため、複数ページにわたる大規模なスキャンは設計上遅くなります。呼び出しを最小限に抑えるには、where フィルター(例: modifiedDate>='...')と fields パラメータを使用してください。

プロンプトの例

• 「CTS001 の在庫はブランチ全体でどれくらいありますか?」 → Stock に対して where: "code='CTS001'" を指定して cin7_list

• 「今週出荷された $500 を超える受注を表示して」 → SalesOrders に対して where フィルターを指定して cin7_list

• 「サプライヤー X 向けにこれらの明細で発注書を作成して…」 → PurchaseOrders を cin7_describe で確認してから cin7_create

• 「Contact にはどのようなフィールドがありますか?」 → Contacts を cin7_describe

開発

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

ビルドは同じソースから 2 つのバンドルを生成します:dist/index.js(ESM、クローンして実行する場合 / Claude Code 用)と server/index.cjs(CJS、.mcpb 拡張機能にパッケージ化されます)。

src/fieldReference.ts は、scripts/gen_fields.py によって Cin7 の公式 swagger 仕様から生成されます(作業ディレクトリに https://api.cin7.com/api/swagger/v1/swagger.json から取得した swagger.json が必要です)— Cin7 が API を更新した場合は再生成してください。

対象外

• Cin7 Omni の webhook(プッシュ通知)— このサーバーはリクエスト/レスポンスのみです。

• Cin7 が v1/v2 API で公開していないもの。

• リモート/HTTP デプロイ — これはローカルの stdio サーバーです。streamable-HTTP エントリーポイントは後で追加できる可能性があります。