@theyahia/mindbox-mcp

MCP-Server für die Mindbox-CDP-API – Kundenprofile, Bestellungen, Segmente, Produktlisten und beliebige Operationen.

Funktionen

• 6 Tools für die Arbeit mit der Mindbox-API

• Transport: stdio (Standard) und Streamable HTTP (--http)

• Kompatibel mit Claude Desktop, Claude Code, Cursor, Smithery

• Wiederholungen mit Backoff und Idempotenz (transactionId), Schutz des HTTP-Transports

• Skills zur Automatisierung typischer Szenarien

Related MCP server: MoySklad MCP Server

Installation

Claude Desktop

{
  "mcpServers": {
    "mindbox": {
      "command": "npx",
      "args": ["-y", "@theyahia/mindbox-mcp"],
      "env": {
        "MINDBOX_API_KEY": "ваш_ключ",
        "MINDBOX_ENDPOINT_ID": "ваш_endpoint_id"
      }
    }
  }
}

Claude Code

claude mcp add mindbox -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id -- npx -y @theyahia/mindbox-mcp

Streamable HTTP

MINDBOX_API_KEY=ваш_ключ MINDBOX_ENDPOINT_ID=ваш_endpoint_id npx @theyahia/mindbox-mcp --http
# MCP endpoint: http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/health

Standardmäßig lauscht der Server auf 127.0.0.1 (siehe Abschnitt Sicherheit). Der Port wird über PORT, der Host über HOST festgelegt.

Docker (HTTP)

docker build -t mindbox-mcp .
docker run --rm -p 3000:3000 \
  -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id \
  -e MINDBOX_HTTP_ALLOWED_HOSTS=ваш-домен:3000 \
  mindbox-mcp

Der Container lauscht auf 0.0.0.0:3000. Fügen Sie hinter einem Reverse-Proxy Ihren Host zu MINDBOX_HTTP_ALLOWED_HOSTS hinzu (DNS-Rebinding-Schutz).

Smithery

Die Datei smithery.yaml ist enthalten. Erforderliche Parameter: MINDBOX_API_KEY, MINDBOX_ENDPOINT_ID.

Autorisierung und Endpunkte

Autorisierungs-Header: Authorization: Mindbox secretKey="...".

Anfragen gehen an POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…:

• sync – Operationen mit Antwort (Kundenprofil, Segmente, Bestellungserstellung, Produktliste). Wird standardmäßig verwendet.

• async – Fire-and-forget-Ereignisse (Ansichten, Warenkorb-Adds). Verfügbar für run_operation über mode: "async".

Systemnamen von Operationen (operation) werden in jedem Mindbox-Projekt konfiguriert – das sind keine universellen eingebauten Methoden. Standardwerte wie Website.GetCustomerInfo sind nur eine verbreitete Konvention; der Projektadministrator muss Operationen mit übereinstimmenden Systemnamen erstellen, sonst gibt Mindbox ProtocolError zurück.

Umgebungsvariablen

Tools (6)

Sicherheit

• run_operation führt eine BELIEBIGE Mindbox-Operation unter Ihrem geheimen Schlüssel aus und kann Daten ändern. In nicht vertrauenswürdigen Agentenszenarien ist dies ein Vektor für Prompt-Injection. Aufrufe werden in stderr protokolliert; vollständig deaktivieren – MINDBOX_ALLOW_RAW=0.

• HTTP-Transport hat keine eingebaute Authentifizierung, außer dem optionalen MINDBOX_HTTP_TOKEN. Der Server lauscht standardmäßig auf 127.0.0.1, DNS-Rebinding-Schutz ist aktiviert (Validierung von Host/Origin), CORS * ist nur auf /health erlaubt. Für den Fernzugriff setzen Sie ihn hinter einen authentifizierenden Reverse-Proxy und öffnen Sie den Port nicht unnötig nach außen.

• Der geheime Schlüssel wird nur serverseitig verwendet und darf niemals in den Browser gelangen.

Skills

Beispielanfragen

Найди клиента с email user@example.com
Создай заказ для клиента с телефоном +7900...
Какие сегменты у клиента user@example.com?
Покажи список товаров
Обнови имя клиента с ID 12345
Выполни операцию Custom.GetData с телом {"key": "value"}

Fehlerbehebung

Entwicklung

npm install          # установка + сборка (prepare)
npm run dev          # stdio
npm run dev:http     # HTTP на порту 3000
npm test             # Vitest
npm run typecheck    # tsc --noEmit
npm run lint         # ESLint

Siehe CONTRIBUTING.md.

Lizenz

MIT