Cin7 Omni MCP Server

Claude에게 Cin7 Omni API에 대한 전체 액세스를 제공하는 MCP 서버입니다 — API가 지원하는 모든 리소스와 모든 작업을 포함합니다:

Contacts · Branches · Product Categories · Products · Product Options · Product Images · Size Ranges · Stock · Serial Numbers · Branch Transfers · Adjustments · Vouchers · Sales Orders (incl. cartons) · 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에서: Settings (⚙) → Integrations → API v1 → Add API Connection. 이렇게 하면 API Username과 API Key가 제공됩니다(Basic-auth 자격 증명이며, Cin7 로그인이 아닙니다). Claude가 접근하길 원하는 모듈에 연결 권한을 부여하세요 — 권한이 없는 모듈은 403을 반환합니다.

2. 다운로드 dist/cin7-omni.mcpb — 단일 파일, 약 150KB.

3. 열기 — 파일을 더블클릭하거나(또는 Claude Desktop: Settings → Extensions → 파일을 끌어다 놓기) Install을 클릭하세요. 메시지가 표시되면 API Username과 API Key를 붙여넣으세요. 키는 컴퓨터의 키체인에 저장되며 파일에는 절대 저장되지 않습니다. Claude를 조회 전용으로 제한하려면 Read-only mode 토글도 있습니다.

그런 다음 Claude에게 *"Cin7 SalesOrders 리소스에 대해 설명해 줘"*라고 물어보면 정상 작동을 확인할 수 있습니다.

나중에 제거하려면: Claude Desktop → Settings → Extensions → Cin7 Omni → Uninstall.

다른 실행 방법

사전 빌드된 자체 포함 서버도 저장소에 함께 제공됩니다(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에 추가(Settings → Developer → Edit Config):

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

환경 변수

쓰기 액세스 제어

두 가지 계층:

1. Claude의 도구별 권한 — Claude가 처음 cin7_create, cin7_update, cin7_delete 또는 cin7_upload_product_image를 호출하면 프롬프트가 표시되며 도구별로 한 번 허용, 항상 허용, 거부 중 하나를 선택할 수 있습니다(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에 대한 구매 주문을 생성해 줘…" → cin7_describe로 PurchaseOrders 확인 후 cin7_create 실행

• "Contact에는 어떤 필드가 있나요?" → cin7_describe로 Contacts 확인

개발

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

빌드는 동일한 소스에서 두 개의 번들을 생성합니다: 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 웹훅(푸시 알림) — 이 서버는 요청/응답 방식만 지원합니다.

• Cin7이 v1/v2 API를 통해 노출하지 않는 모든 것.

• 원격/HTTP 배포 — 로컬 stdio 서버이며, streamable-HTTP 진입점은 나중에 추가할 수 있습니다.