@theyahia/mindbox-mcp

Mindbox CDP API용 MCP 서버 — 고객 프로필, 주문, 세그먼트, 상품 목록 및 임의 작업.

기능

• Mindbox API 작업을 위한 6가지 도구

• 전송: stdio(기본값) 및 Streamable HTTP(--http)

• Claude Desktop, Claude Code, Cursor, Smithery 호환

• 백오프(backoff) 및 멱등성(transactionId)을 갖춘 재시도, HTTP 전송 보호

• 일반적인 시나리오 자동화를 위한 Skills

Related MCP server: MoySklad MCP Server

설치

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

기본적으로 서버는 127.0.0.1에서 수신합니다(보안 섹션 참조). 포트는 PORT, 호스트는 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

컨테이너는 0.0.0.0:3000에서 수신합니다. 리버스 프록시 뒤에서 사용하는 경우 MINDBOX_HTTP_ALLOWED_HOSTS에 자체 호스트를 추가하세요(DNS-rebinding 보호).

Smithery

smithery.yaml 파일이 포함되어 있습니다. 필수 매개변수: MINDBOX_API_KEY, MINDBOX_ENDPOINT_ID.

인증 및 엔드포인트

인증 헤더: Authorization: Mindbox secretKey="...".

요청은 POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…로 전송됩니다:

• sync — 응답이 있는 작업(고객 프로필, 세그먼트, 주문 생성, 상품 목록). 기본값으로 사용됩니다.

• async — fire-and-forget 이벤트(조회, 장바구니 추가). run_operation에서 mode: "async"로 사용할 수 있습니다.

작업의 시스템 이름(operation)은 각 Mindbox 프로젝트에서 설정됩니다 — 보편적인 내장 메서드가 아닙니다. Website.GetCustomerInfo 같은 기본값은 흔한 관례일 뿐입니다. 프로젝트 관리자가 동일한 시스템 이름으로 작업을 생성해야 하며, 그렇지 않으면 Mindbox가 ProtocolError를 반환합니다.

환경 변수

도구 (6)

보안

• **run_operation**은 비밀 키로 임의의 Mindbox 작업을 실행하며 데이터를 변경할 수 있습니다. 신뢰할 수 없는 에이전트 시나리오에서는 prompt-injection 벡터가 될 수 있습니다. 호출은 stderr에 기록됩니다. 완전히 비활성화하려면 MINDBOX_ALLOW_RAW=0을 설정하세요.

• HTTP 전송에는 선택적 MINDBOX_HTTP_TOKEN 외에 내장 인증이 없습니다. 서버는 기본적으로 127.0.0.1에서 수신하며, DNS-rebinding 보호(Host/Origin 검증)가 활성화되어 있고, CORS *는 /health에서만 허용됩니다. 원격 액세스의 경우 인증 리버스 프록시 뒤에 배치하고 필요 없으면 포트를 외부에 열지 마세요.

• 비밀 키는 서버 측에서만 사용되며 브라우저에 절대 노출되어서는 안 됩니다.

Skills

요청 예시

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

문제 해결

개발

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

CONTRIBUTING.md 참조.

라이선스

MIT