granter-cli

Granter API를 위한 CLI & MCP 서버. 세금계산서, 현금영수증, 거래 내역, 급여, 재고, 전자결재까지 — 터미널 하나로 자동화합니다.

설치

npm install -g @granter-biz/cli@latest --ignore-scripts

sudo npm install -g는 사용하지 마세요. 권한 오류가 나면 npm의 global prefix를 사용자 소유 경로로 바꾸거나 nvm/fnm/volta 같은 Node 버전 매니저를 사용한 뒤 다시 설치하세요.

안전한 설치/검증

설치 전 npm registry의 패키지 메타데이터를 확인하세요:

npm view @granter-biz/cli@latest name version repository.url maintainers dist.integrity dist.tarball

확인할 기준:

• 패키지명은 정확히 @granter-biz/cli입니다.
• maintainer는 granter-biz <[email protected]>입니다.
• repository.url은 github.com/granter-biz/granter-cli입니다.
• dist.integrity 값은 npm registry가 제공하는 tarball 무결성 값입니다. 버전별 값은 GitHub Release 노트에도 함께 기록합니다.

설치 후에는 실행 파일과 버전을 확인하세요:

granter --version
granter --help

로컬에서 테스트

git clone https://github.com/granter-biz/granter-cli.git
cd granter-cli
npm install
npm run build
npm link          # granter, granter-mcp 명령어를 로컬에 등록
granter --help

MCP 서버도 바로 연결할 수 있습니다:

# Claude Code
claude mcp add granter -- granter-mcp

# 또는 절대 경로로
claude mcp add granter -- node /path/to/granter-cli/dist/mcp.js

설정

CLI 인증이 활성화된 환경에서는 브라우저에서 그랜터에 로그인하거나 회원가입한 뒤 API 키를 자동으로 저장합니다:

granter init

테스트 키를 저장하려면:

granter init --key-type test

이미 API 키를 발급받았다면 직접 설정할 수도 있습니다:

granter config --api-key YOUR_API_KEY

설정 확인:

granter config --show

API 탐색

CLI가 지원하는 Public API 전체 목록과 연결된 CLI 명령을 확인할 수 있습니다:

granter apis
granter apis --group assets
granter apis --group manual
granter apis --group organizations
granter apis --group workspace
granter apis --kind write
granter apis --search salary
granter apis show daily-financial-report
granter apis show daily-financial-report --format json
granter apis --json

사용법

조회

# 카드 사용 내역
granter tickets --type EXPENSE_TICKET --from 2026-04-01 --to 2026-04-30

# 계좌 입출금
granter tickets --type BANK_TRANSACTION_TICKET --from 2026-04-01 --to 2026-04-16

# 티켓 계정과목/태그/설명 수정
granter tickets-update --file ticket-update.json

# 티켓 데이터 갱신 요청
granter tickets-refresh

# 티켓 간 연결 생성/갱신
granter ticket-references create --file ticket-reference.json --idempotency-key ticket-ref-001

# 기관 연동 상태 / 로그인 연동
granter organizations
granter organizations --is-connected true
granter organizations login-connect --file organization-login-connect.json
granter organizations login-reconnect --file organization-login-reconnect.json

# 자산 목록 (카드, 계좌, 홈택스 등)
granter assets --type CARD
granter assets --type BANK_ACCOUNT
granter assets --type HOME_TAX_ACCOUNT

# 수기 자산 / 거래 입력
granter cards create --file card-create.json --idempotency-key card-001
granter bank-accounts create --file bank-account-create.json --idempotency-key bank-account-001
granter card-usages create --file card-usages-create.json --idempotency-key card-usages-001
granter bank-transactions create --file bank-transactions-create.json --idempotency-key bank-transactions-001

# 계좌 잔액 추이
granter balances --from 2026-04-01 --to 2026-04-16

# 자금일보
granter daily-financial-report --from 2026-04-01 --to 2026-04-16

# 워크스페이스 / 사용자 / 요금제
granter workspace-profile
granter user-profiles
granter subscription

# 거래처 / 구성원 / 팀
granter contacts
granter people
granter teams

# 계정과목 / 태그
granter categories
granter tags
granter tag-details

# 기준 데이터 생성/수정
granter tags create --file tag-create.json --idempotency-key tag-create-001
granter tags update --file tag-update.json
granter tag-details create --file tag-detail-create.json
granter tag-details update --file tag-detail-update.json
granter categories create --file category-create.json
granter categories update --file category-update.json
granter contacts create --file contact-create.json
granter contacts update --file contact-update.json
granter people invite --file people-invite.json

# 전자결재
granter workflows --status PENDING
granter workflows create --file workflow-create.json

# 급여 내역
granter salary --from 2026-03-01 --to 2026-03-31
granter salary create --file salary-create.json

# 재고
granter inventory products
granter inventory stock

# 근태 / 연차
granter attendance list --from 2026-04-01 --to 2026-04-16
granter attendance leave-balances
granter attendance leave-histories --from 2026-01-01 --to 2026-04-16

# 환율 / 공휴일
granter exchange-rates --base-date 2026-04-16
granter holidays --from 2026-04-01 --to 2026-04-30

세금계산서 발행

JSON 파일로 payload를 작성한 뒤 발행합니다:

# 수기 세금계산서 기록 생성
granter invoice create --file tax-invoice-create.json --idempotency-key tax-invoice-001

# 발행
granter invoice issue --file invoice.json

# 수정발행
granter invoice modify --file modify.json

# 취소발행
granter invoice cancel --file cancel.json

{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-16",
  "issueScheduleType": "IMMEDIATE",
  "purposeType": "CHARGE",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 110000,
  "note": "4월 개발 용역",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "공급자 회사",
    "name": "담당자명",
    "email": "[email protected]",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구",
    "id": 101
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "거래처 회사",
    "name": "구매담당자",
    "email": "[email protected]",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구",
    "id": 202
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-16",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ],
  "memo": ""
}

현금영수증

# 수기 현금영수증 기록 생성
granter cash-receipt create --file cash-receipt-create.json --idempotency-key cash-receipt-001

# 발행
granter cash-receipt issue --file receipt.json

# 취소
granter cash-receipt cancel --file cancel-receipt.json

MCP 서버 (AI 연동)

Claude Code, Claude Desktop 등 AI 도구와 연동하면 자연어로 Granter API를 사용할 수 있습니다.

Claude Code

claude mcp add granter -- granter-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "granter": {
      "command": "granter-mcp"
    }
  }
}

연동 후 이렇게 사용합니다

"이번 달 카드 사용 내역 보여줘"

"주식회사 베타에 4월분 세금계산서 100만원 발행해줘"

"3월 급여 내역 조회해줘"

"잔여 연차 확인해줘"

"오늘 환율 알려줘"

지원 API와 탐색 도구가 MCP에 등록되어 Granter API 기능을 자연어로 호출할 수 있습니다.

지원하는 API

| 도메인 | 명령어 | 설명 | |--------|--------|------| | 거래/증빙 | tickets tickets-update tickets-refresh ticket-references create | 카드, 계좌, 세금계산서, 현금영수증 조회, 갱신, 티켓 보정/연결 | | 자산 | assets | 카드, 계좌, 홈택스 연동 현황 | | 수기 입력 | cards create bank-accounts create card-usages create bank-transactions create invoice create cash-receipt create | 수기 자산, 거래, 증빙 기록 생성 | | 잔액 | balances | 계좌별 잔액 시계열 | | 기준 데이터 | tags tag-details categories people contacts teams | 분류/담당자/거래처 | | 전자결재 | workflows | 결재 문서 및 승인 상태 | | 급여 | salary | 급여 내역, 공제, 수당 | | 재고 | inventory products inventory stock | 품목 마스터, 재고 수량 | | 근태 | attendance list attendance leave-balances attendance leave-histories | 출결, 연차 | | 기타 | exchange-rates holidays | 환율, 공휴일 | | 세금계산서 | invoice issue invoice modify invoice cancel | 발행/수정/취소 | | 현금영수증 | cash-receipt issue cash-receipt cancel | 발행/취소 |

License

MIT