lightspeed-x-mcp

Lightspeed X(이전 명칭 Vend로 알려진 Lightspeed Retail POS)용 Model Context Protocol 서버입니다. Claude 또는 모든 MCP 클라이언트에 매장의 매출, 재고, 상품, 고객에 대한 읽기 전용 액세스를 제공하며, 집계도 직접 처리합니다: 매출, 수량, 매출원가(COGS), 총이익, 마진, 할인, 평균 장바구니 금액, 장바구니 크기를 요청한 차원별로 그룹화하여 제공합니다.

구조적으로 읽기 전용입니다. 모든 도구는 GET 요청만 실행합니다. 이 서버에는 계정에서 무엇이든 생성, 업데이트, 삭제할 수 있는 코드 경로가 없으므로, 걱정 없이 실제 소매 사업에 연결해도 됩니다.

"What sold best yesterday?"                → lightspeed_sales_report
"Revenue by store last week"               → lightspeed_sales_report, group_by: outlet
"Which SKUs need reordering?"              → lightspeed_inventory_report, status: reorder_needed
"What are our busiest hours?"              → lightspeed_sales_report, group_by: hour
"Margin by brand this month"               → lightspeed_sales_report, group_by: brand
"Pull up invoice 162220"                   → lightspeed_list_sales

왜 이런 서버가 필요한가

Lightspeed X API는 Vend 시대의 유산이며, 순진한 클라이언트를 느리게 만들거나 조용히 잘못된 결과를 내게 만드는 몇 가지 날카로운 모서리가 있습니다. 이 서버는 모델이 그런 문제를 처리할 필요가 없도록 대신 처리합니다:

매출 수학이 어떻게 도출되는가

연속된 200건의 실제 매출로 검증했습니다. 모든 건이 해당 매출의 totals.price와 2센트 이내로 일치했습니다:

line revenue excl tax = line_items[].pricing.total        (net of discount, already x quantity)
line COGS             = line_items[].pricing.cost_total
line discount given   = line_items[].pricing.discount_total
line tax              = line_items[].tax.total

실제 데이터에 대한 세 가지 추가 검증, 모두 정확히 일치:

• 일주일간 일별 매출의 합은 해당 주의 총합과 같습니다.

• group_by: outlet 보고서의 아울렛 행은 해당 아울렛의 서버 측 필터로 다시 실행한 동일 보고서와 같습니다.

• 결제 수단별 수취 금액의 합은 세금 포함 매출과 같습니다.

Related MCP server: mcp-pdv-demo

설치

옵션 1: Claude Code 플러그인으로 설치(권장)

명령 3개, 클론 없음, 빌드 없음, 수정할 경로 없음:

/plugin marketplace add genvjacobc/lightspeed-x-mcp
/plugin install lightspeed-x@lightspeed-x-mcp
/lightspeed-x:setup

세 번째 명령은 번들된 설정 스킬을 실행하여 토큰을 얻는 과정을 안내하고, 올바른 위치에 토큰을 기록한 다음, 실제 계정에 대한 연결을 확인한 후에야 성공했다고 알려줍니다.

플러그인에는 reports 스킬도 포함되어 있어 Claude가 어떤 도구가 어떤 유형의 소매 질문에 답하는지, 그리고 받은 숫자를 어떻게 읽는지 알 수 있습니다.

자격 증명은 ${CLAUDE_PLUGIN_DATA}/credentials.env에 저장되며, 플러그인 업데이트 후에도 유지되는 사용자별 디렉터리입니다. 머신이나 팀원 간에 공유되는 것은 없습니다.

/plugin uninstall은 해당 디렉터리를 삭제하므로, 제거 후 재설치하면 설정을 다시 실행해야 합니다. 토큰 자체는 Lightspeed에서 계속 유효하므로, 사용이 끝났다면 해당 화면에서 토큰을 폐기하세요.

옵션 2: 독립형 MCP 서버로 설치

git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run build

Node 18 이상이 필요합니다.

API 토큰 받기

Lightspeed X 백오피스에서: 설정 → 개인 토큰 → 개인 토큰 추가. 대화 상자를 닫기 전에 복사하세요. 한 번만 표시됩니다.

배포를 계획하기 전에 알아야 할 두 가지 제한 사항:

• 관리자 사용자만 개인 토큰을 만들 수 있으며, Lightspeed는 이 기능을 Plus 요금제로 제한합니다. 설정 아래에 개인 토큰이 표시되지 않으면 관리자 권한이 있는 사람이 토큰을 만들어야 합니다.

• Lightspeed는 읽기 전용 토큰을 제공하지 않습니다. 토큰은 토큰을 만든 사용자의 모든 권한을 가집니다. 이 서버는 GET만 실행하지만, 토큰 자체는 범용 자격 증명이므로 비밀번호처럼 취급하고 유출된 경우 같은 화면에서 폐기하세요.

작동 확인

npm run doctor

이 명령은 자격 증명을 검증하고, 실제 API를 호출하며, 실패의 정확한 원인을 명명합니다. 잘못된 스토어 도메인과 잘못된 토큰 모두 Lightspeed에서 HTTP 401을 반환하므로, 의사 도구는 추측 대신 두 가지 가능성을 모두 보고합니다.

구성

.env.example을 .env로 복사하고 매장 정보를 입력하세요:

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN은 접두사만(mystore), 호스트(mystore.retail.lightspeed.app), 또는 전체 URL을 허용합니다. 세 가지 모두 동일한 위치로 해석됩니다.

여러 매장. LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN 쌍은 소문자로 된 <name>이라는 계정을 정의합니다. 그러면 도구는 선택적 account 인수를 받습니다:

LIGHTSPEED_NORTH_DOMAIN=northstore
LIGHTSPEED_NORTH_TOKEN=token_for_north
LIGHTSPEED_SOUTH_DOMAIN=southstore
LIGHTSPEED_SOUTH_TOKEN=token_for_south
LIGHTSPEED_DEFAULT_ACCOUNT=north

환경에 이미 있는 값은 항상 .env 파일보다 우선하므로, 자격 증명을 직접 주입하는 호스트가 우선권을 가집니다.

Claude Code에 등록(독립형 경로만 해당)

플러그인을 설치했다면 이 단계를 건너뛰세요. 플러그인이 서버를 자체 등록합니다.

claude mcp add lightspeed-x -s user -- node /absolute/path/to/lightspeed-x-mcp/dist/index.js

또는 구성에 수동으로 추가:

{
  "mcpServers": {
    "lightspeed-x": {
      "command": "node",
      "args": ["/absolute/path/to/lightspeed-x-mcp/dist/index.js"],
      "env": {
        "LIGHTSPEED_DOMAIN": "mystore",
        "LIGHTSPEED_TOKEN": "your_personal_token"
      }
    }
  }
}

Claude Desktop의 경우 동일한 블록을 claude_desktop_config.json에 넣습니다.

MCP Inspector로 로컬에서 검증하세요:

npm run inspect

도구

lightspeed_sales_report

핵심 기능입니다. 날짜 범위를 집계하고 그룹화합니다.

| Outlet          |   Revenue | Units | Sales | Basket value | Gross profit | Margin |
| --------------- | --------: | ----: | ----: | -----------: | -----------: | -----: |
| South Lincoln   | $3,401.60 |   193 |    91 |       $37.38 |    $2,342.35 |  68.9% |
| York            | $3,222.86 | 159.2 |    73 |       $44.15 |    $2,238.77 |  69.5% |

lightspeed_list_sales

개별 거래를 최신순으로 반환하며, 선택적으로 라인 항목 확장을 지원합니다. 영수증 하나를 자세히 보거나, 합계를 감사하거나, 반품을 확인할 때 사용합니다. outlet_id, customer_id, min_total 필터를 지원합니다.

lightspeed_inventory_report

상품 및 아울렛 이름과 결합된 보유 재고와, 선반에 있는 재고의 소매 가치 및 원가 가치를 제공합니다.

status가 핵심 인수입니다:

group_by는 product, outlet, category, brand, supplier로 롤업되며, "각 카테고리에 얼마나 많은 재고 가치가 있는가"라는 질문에 답하는 방법입니다.

lightspeed_search_products

이름, 변형 이름, SKU, 핸들에 대한 자유 텍스트 검색으로, 브랜드 / 공급업체 / 카테고리 / 태그 필터를 지원합니다. API 자체 검색 엔드포인트의 순위 품질이 낮기 때문에 캐시된 카탈로그에 대해 로컬에서 일치를 실행하므로, 결과는 정확한 부분 문자열 일치입니다.

lightspeed_get_product

ID 또는 정확한 SKU로 한 상품의 전체 세부 정보를 제공하며, 아울렛별 재고와 계산된 마진을 포함합니다.

lightspeed_search_customers / lightspeed_get_customer

이메일(API에 전달) 또는 이름, 전화번호, 고객 코드(로컬에서 일치)로 고객을 조회합니다. 매출 도구가 customer_id 필터로 사용하는 UUID를 반환합니다. 이는 개인 데이터를 반환하므로 적절히 처리하세요.

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

매장 이름을 보고서 필터가 사용하는 아울렛 UUID로 변환하고, 전자상거래 레지스터를 포함한 POS 라인을 나열하며, 서버가 연결할 수 있는 계정을 확인합니다. lightspeed_list_accounts는 토큰을 절대 반환하지 않습니다.

lightspeed_list_reference_data

brands, suppliers, product_categories, tags, customer_groups, payment_types, promotions, taxes, users를 다루는 하나의 도구입니다. 보고서를 필터링하기 전에 브랜드나 카테고리의 정확한 철자를 확인하는 데 사용하세요.

lightspeed_api_get

전용 도구가 없는 모든 엔드포인트를 위한 탈출구: /consignments, /price_books, /serial_numbers 등. 오직 GET만 발행됩니다.

성능 및 제한

보고서는 판매를 서버 측에서 날짜로 필터링할 수 없다는 사실에 의해 형성됩니다.

콜드 호출의 대부분은 날짜 범위를 찾는 ~30개의 단일 행 프로브입니다. 이러한 프로브는 계정별로 기억되므로 세션의 두 번째 보고서는 일반적으로 필요하지 않습니다. 카탈로그, 매장, 레지스터, 사용자 및 재고 스캔은 15분 동안 캐시됩니다.

빠르게 유지하려면: 한 매장에만 관심이 있을 때 outlet_id를 전달하고, 좁은 날짜 범위를 선호하세요. LIGHTSPEED_MAX_SALES(기본값 200,000)는 단일 호출을 제한하며, 도구는 부분적인 답변을 조용히 반환하는 대신 잘릴 때 명확하게 알려줍니다.

솔직한 경고 하나. 날짜 범위는 버전으로 찾기 때문에 범위 이전에 생성되었지만 이후에 편집된 판매는 누락될 수 있습니다. LIGHTSPEED_SEEK_MARGIN_DAYS(기본값 1)는 검색이 범위보다 얼마나 앞서 목표를 설정하는지 결정하며, 이를 높이면 더 많은 레코드를 스캔하는 대신 안전망이 넓어집니다. 이는 날짜로 필터링하지 않는 API의 고유한 특성이며, 여기서 취한 지름길이 아닙니다.

구성 참조

개발

npm run dev      # run from source with tsx
npm run build    # compile to dist/
npm run inspect  # MCP Inspector against the built server
npm run doctor   # credentials + live connectivity check
npm run validate-plugin  # validate the plugin manifests

src/
  index.ts            entry point, env loading, tool registration
  config.ts           account discovery from the environment
  lib/
    client.ts         HTTP client, retry, version pagination
    version-seek.ts   date to version binary search
    sales.ts          sale fetching and metric aggregation
    catalog.ts        cached product, outlet, register, inventory lookups
    time.ts           timezone-aware day boundaries
    format.ts         Markdown table rendering, tool results
  tools/              one file per tool group

도구는 원시 JSON 대신 Markdown 테이블을 반환합니다. 모델은 깊은 JSON 블롭보다 정렬된 테이블을 더 안정적으로 읽을 수 있으며, 토큰의 일부만 사용합니다. 기본 숫자는 프로그래밍 방식 호출자를 위해 structuredContent에도 있습니다.

기여할 때 유지할 만한 두 가지 규칙:

• 도구 핸들러에서 절대 throw하지 마세요. 실패는 isError 결과로 반환됩니다. guard() 래퍼가 이를 강제합니다.

• 절대 console.log를 사용하지 마세요. Stdout은 JSON-RPC 프레임을 전달합니다. 진단은 console.error로 보냅니다.

저장소 구조

.claude-plugin/     plugin + marketplace manifests
.mcp.json           MCP server declaration used by the plugin path
skills/setup/       guided connection walkthrough
skills/reports/     how to answer retail questions with these tools
src/                TypeScript source
dist/               compiled output, committed so plugin installs need no build

dist/는 의도적으로 git에 추적됩니다. Claude Code 플러그인 설치가 빌드 단계를 실행하지 않고 컴파일된 서버가 저장소와 함께 배포되어야 하기 때문입니다. 소스 변경을 커밋하기 전에 npm run build를 실행하고, 릴리스 시 package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json의 version을 함께 올리세요.

라이선스

MIT. LICENSE 참조.

Lightspeed Commerce와 제휴하거나 보증하지 않습니다.