@theyahia/mindbox-mcp

Servidor MCP para la API de Mindbox CDP: perfiles de clientes, pedidos, segmentos, listas de productos y operaciones arbitrarias.

Características

• 6 herramientas para trabajar con la API de Mindbox

• Transporte: stdio (por defecto) y Streamable HTTP (--http)

• Compatibilidad con Claude Desktop, Claude Code, Cursor, Smithery

• Reintentos con backoff e idempotencia (transactionId), protección del transporte HTTP

• Skills para automatizar escenarios típicos

Related MCP server: MoySklad MCP Server

Instalación

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

Por defecto, el servidor escucha en 127.0.0.1 (consulte la sección Seguridad). El puerto se configura mediante PORT, el host mediante HOST.

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

El contenedor escucha en 0.0.0.0:3000. Detrás de un proxy inverso, añada su host a MINDBOX_HTTP_ALLOWED_HOSTS (protección contra DNS-rebinding).

Smithery

El archivo smithery.yaml está incluido. Parámetros requeridos: MINDBOX_API_KEY, MINDBOX_ENDPOINT_ID.

Autorización y endpoints

Cabecera de autorización: Authorization: Mindbox secretKey="...".

Las solicitudes se envían a POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…:

• sync — operaciones con respuesta (perfil de cliente, segmentos, creación de pedido, lista de productos). Se usa por defecto.

• async — eventos fire-and-forget (vistas, adiciones al carrito). Disponible para run_operation mediante mode: "async".

Los nombres de sistema de las operaciones (operation) se configuran en cada proyecto de Mindbox — no son métodos integrados universales. Valores por defecto como Website.GetCustomerInfo son solo una convención común; el administrador del proyecto debe crear operaciones con nombres de sistema coincidentes; de lo contrario, Mindbox devolverá ProtocolError.

Variables de entorno

Herramientas (6)

Seguridad

• run_operation ejecuta una operación ARBITRARIA de Mindbox con su clave secreta y puede modificar datos. En escenarios de agentes no confiables, esto es un vector de prompt-injection. Las llamadas se registran en stderr; para desactivarlo por completo, use MINDBOX_ALLOW_RAW=0.

• El transporte HTTP no tiene autenticación integrada, salvo el MINDBOX_HTTP_TOKEN opcional. El servidor escucha por defecto en 127.0.0.1, con protección contra DNS-rebinding habilitada (validación de Host/Origin); CORS * solo está permitido en /health. Para acceso remoto, colóquelo detrás de un proxy inverso con autenticación y no exponga el puerto hacia el exterior sin necesidad.

• La clave secreta se usa solo en el lado del servidor y nunca debe llegar al navegador.

Skills

Ejemplos de solicitudes

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

Solución de problemas

Desarrollo

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

Consulte CONTRIBUTING.md.

Licencia

MIT