Cin7 Omni MCP Server

Ein MCP-Server, der Claude vollständigen Zugriff auf die Cin7 Omni API bietet — auf jede Ressource und jede Operation, die die API unterstützt:

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

Die Verben-Matrix (welche Ressourcen aufgelistet, abgerufen, erstellt, aktualisiert oder gelöscht werden können) stammt aus der offiziellen Swagger-Spezifikation von Cin7 und wird vom Server durchgesetzt, sodass Claude niemals eine Operation versuchen kann, die die API nicht unterstützt.

Tools

Lese- und Schreiboperationen sind getrennte Tools mit entsprechenden MCP-Annotationen (readOnlyHint, destructiveHint). In Claude kannst du daher jedes Schreib-Tool unabhängig von den Lese-Tools auf Immer erlauben, Jedes Mal fragen oder Ablehnen setzen.

Related MCP server: GHL MCP Server

Installation in Claude Desktop (3 Schritte, keine Konfigurationsänderungen)

1. Cin7-API-Zugangsdaten besorgen — in Cin7 Omni: Einstellungen (⚙) → Integrationen → API v1 → API-Verbindung hinzufügen. Das liefert dir einen API Username und einen API Key (Basic-Auth-Zugangsdaten, nicht dein Cin7-Login). Erteile der Verbindung Zugriff auf die Module, die Claude erreichen soll — ein Modul ohne Berechtigung liefert 403 zurück.

2. Lade dist/cin7-omni.mcpb herunter — eine Datei, ~150 KB.

3. Öffne sie — doppelklicke die Datei (oder in Claude Desktop: Einstellungen → Erweiterungen → Datei hineinziehen) und klicke auf Installieren. Füge bei Aufforderung den API Username und den API Key ein; der Schlüssel wird im Schlüsselbund deines Computers gespeichert, niemals in einer Datei. Es gibt außerdem einen Schalter für den Nur-Lese-Modus, falls du Claude auf reine Abfragen beschränken möchtest.

Frage Claude anschließend etwas wie "describe the Cin7 SalesOrders resource", um zu bestätigen, dass alles funktioniert.

Zum späteren Entfernen: Claude Desktop → Einstellungen → Erweiterungen → Cin7 Omni → Deinstallieren.

Weitere Ausführungsmöglichkeiten

Ein vorgefertigter, eigenständiger Server ist ebenfalls im Repository enthalten (dist/index.js — alle Abhängigkeiten sind gebündelt), sodass Klonen zum Ausführen genügt: kein npm install, kein Build-Schritt. git pull liefert dir immer den neuesten, testbereiten Build.

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

Nur wenn du den Quellcode selbst bearbeitest: npm install (baut automatisch) oder npm run build, um neu zu bauen.

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 (manuelle Konfiguration) — füge Folgendes zu claude_desktop_config.json hinzu (Einstellungen → Entwickler → Konfiguration bearbeiten):

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

Umgebungsvariablen

Schreibzugriff steuern

Zwei Ebenen:

1. Claudes Berechtigungen pro Tool — wenn Claude cin7_create, cin7_update, cin7_delete oder cin7_upload_product_image zum ersten Mal aufruft, wirst du gefragt und kannst pro Tool einmal erlauben, immer erlauben oder ablehnen wählen (in Claude Code verwaltest du sie unter /permissions).

2. Harte serverseitige Sperre — setze CIN7_READ_ONLY=true, dann werden die Schreib-Tools gar nicht erst registriert.

Rate-Limits

Cin7 setzt 3 Aufrufe/Sekunde, 60/Minute, 5.000/Tag durch. Der Server stellt Anfragen clientseitig in eine Warteschlange, um unter den Grenzen pro Sekunde/Minute zu bleiben, und wiederholt sie bei 429/5xx automatisch mit Backoff. Große mehrseitige Abrufe sind daher bewusst langsam. Verwende where-Filter (z. B. modifiedDate>='...') und den Parameter fields, um die Anzahl der Aufrufe zu minimieren.

Beispiel-Prompts

• "How much stock of CTS001 do we have across branches?" → cin7_list für Stock mit where: "code='CTS001'"

• "Show me sales orders dispatched this week over $500" → cin7_list für SalesOrders mit einem where-Filter

• "Create a purchase order for supplier X with these lines…" → erst cin7_describe für PurchaseOrders, dann cin7_create

• "What fields does a Contact have?" → cin7_describe für Contacts

Entwicklung

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

Der Build erzeugt aus derselben Quelle zwei Bundles: dist/index.js (ESM, für Klonen und Ausführen / Claude Code) und server/index.cjs (CJS, verpackt in die .mcpb-Erweiterung).

src/fieldReference.ts wird aus der offiziellen Swagger-Spezifikation von Cin7 durch scripts/gen_fields.py generiert (erwartet swagger.json von https://api.cin7.com/api/swagger/v1/swagger.json im Arbeitsverzeichnis) — generiere es neu, falls Cin7 seine API aktualisiert.

Nicht abgedeckt

• Webhooks von Cin7 Omni (Push-Benachrichtigungen) — dieser Server arbeitet nur nach dem Request/Response-Prinzip.

• Alles, was Cin7 nicht über die v1/v2-API bereitstellt.

• Remote-/HTTP-Bereitstellung — dies ist ein lokaler stdio-Server; ein streamable-HTTP-Einstiegspunkt könnte später ergänzt werden.