매월 마지막 주, 다섯 개 은행 사이트를 돌며 거래내역을 내려받아 본 적 있다면 — 그 시간을 줄이는 방법이 있습니다. 같은 일을 Claude Code에 자연어 한 줄로 부탁하면 됩니다.

이 글은 노트북 앞에서 그대로 따라 할 수 있는 단계별 가이드입니다. 받아온 데이터는 내 화면과 내 파일에 머뭅니다. 처음 셋업이라면 약 10분, 다음번부터는 한 줄이면 끝납니다.

무엇을 만들 것인가

마지막에 얻는 결과는 이렇습니다. Claude Code 안에서:

> 지난달 국민은행 입출금내역 받아서 출금 합계만 알려줘

# 잠시 후 …
거래 47건. 출금 합계 ₩12,840,500.
가장 큰 출금은 4/15 ECOUNT-카드자동납부 ₩487,500.

이 한 줄 뒤에서는 다음이 일어납니다.

Claude Code가 h6s_fetch_data MCP 도구를 호출합니다 (provider=CB_KB, schema=bank.transactions.cb.v1, 기간=2026-04).
headless 백엔드가 국민은행에서 거래내역을 받아 표준 데이터 형식에 맞춰 응답합니다.
표준 데이터 형식 배열이 Claude Code로 돌아옵니다.
Claude Code가 필요한 집계와 자연어 요약을 만들어 줍니다.

여기까지 가는 데 필요한 준비물은 세 가지입니다.

Claude Code가 깔린 노트북
h6s.ai 계정 (없으면 30초)
거래내역을 받을 은행의 공동인증서 (또는 ID·비밀번호)

1. headless 계정과 API key (1분)

h6s.ai에서 회원가입 후 콘솔로 들어갑니다. API Keys 메뉴에서 새 키를 발급하면 h6s_live_로 시작하는 문자열이 나오고, 이후 호출에 사용할 수 있습니다.

bash

export H6S_API_KEY=h6s_live_a1b2c3d4...

2. Claude Code 플러그인 설치 (2분)

Claude Code에서 /plugin marketplace 명령으로 headless의 marketplace를 한 번 등록하고, 플러그인을 설치합니다.

/plugin marketplace add bolta-io/h6s-toolkit
/plugin install h6s-data@h6s

설치가 끝나면 Claude Code를 한 번 재시작합니다. 다음 세션부터 h6s_* 도구들이 자연어 호출에 자동으로 노출됩니다.

첫 호출이 느리면 timeout 처럼 보일 수 있습니다. .mcp.json 진입점이 npx -y @h6s-ai/cli 라 처음 한 번 npm cache hydration에 1~2분이 걸립니다. 미리 npm i -g @h6s-ai/cli 로 글로벌 설치해 두면 이 대기를 건너뜁니다.

3. 자격증명 한 번 등록 (3분)

거래내역을 받으려면 그 은행 계정의 자격증명을 headless에 등록합니다. headless는 자격증명을 봉투 암호화(envelope encryption)로 저장하고, 데이터 수집 시점에만 메모리에서 복호화합니다. 등록 후 평문은 어디에도 남지 않습니다.

가장 빠른 길은 공동인증서입니다. PFX 파일 한 번 등록으로 거의 모든 한국 기업뱅킹과 홈택스에 자동 매칭됩니다. 은행마다 자격증명을 따로 만들 필요가 없습니다.

Claude Code에서 자연어로 부탁하면 됩니다. 다만 PFX 비밀번호 같은 민감 값은 Claude Code가 메모리에 잠깐 거쳐 도구 호출로 전달하는 흐름이라, 처음 등록할 때 한 번 동의를 받고 진행합니다.

> headless에 공동인증서 등록해줘. 파일은 ~/Downloads/cert.pfx, 비밀번호는 따로 입력할게.

# Claude Code가 차례로:
# 1. h6s_catalog 호출 → globalCert 입력 폼 fieldKey 확인
# 2. PFX 파일을 읽어 base64 로 인코딩
# 3. 비밀번호는 터미널 secret prompt 로 한 번 입력 (평문이 화면에 안 남음)
# 4. h6s_credentials_create 호출 → { id, credentialHealth: "UNKNOWN" } 반환

공동인증서가 없는 환경이라면 ID·비밀번호로 등록합니다. 같은 도구가 providerCode 만 추가로 받으면 됩니다.

> 신한은행 인터넷뱅킹 ID/비번으로 자격증명 등록할게

등록 후 상태 확인은 h6s_list_credentials 로 합니다.

> headless에 등록된 자격증명 보여줘

자격증명이 살아 있는지는 별도 검증 API가 없습니다. 다음 단계의 데이터 수집을 한 번 실행해 응답이 정상인지 확인합니다. failureCategory: CREDENTIAL이 나오면 그때 자격증명 문제로 좁힙니다.

4. 자연어로 첫 호출 (1분)

이제 자연어 한 줄이 동작합니다.

> 지난달 국민은행 입출금내역 받아줘

응답은 표준 데이터 형식 배열입니다. bank.transactions.cb.v1 데이터 형식의 9개 필드가 고정되어 있습니다 — identifier · transactionAt · accountNumber · accountNumberFormatted · accountType · currencyCode · amount · description · balance.

json

{
  "schemaId": "bank.transactions.cb.v1",
  "identifier": "bank_txn_v1_a1_2b5f0d6c8a91e3f4472c1a9d0e6b8f31",
  "transactionAt": "2026-04-15T14:32:00+09:00",
  "accountNumber": "11012345671234",
  "accountNumberFormatted": "110-1234-5671-234",
  "accountType": "CHECKING",
  "currencyCode": "KRW",
  "amount": -487500,
  "description": "ECOUNT-카드자동납부",
  "balance": 12340500
}

어떤 은행에서 받아도 구조가 같습니다. 한 번 작성한 코드를 그대로 다시 씁니다.

5. 그 다음은 자연어 후처리

거래내역을 받고 나면 그 위에서 자연어로 거의 모든 후처리를 부탁할 수 있습니다.

> 이 거래내역에서 "ECOUNT" 가 들어간 출금만 모아서 CSV로 저장해줘
> 이번 달 50만원 이상 입금만 모아서 CSV로 저장해줘
> 5만원 이상 입금 중에 거래 상대가 처음 보이는 것만 알려줘

같은 흐름이 세금계산서(hometax.tax-invoices.sales.v1) 와 현금영수증(hometax.cash-receipts.sales.v1) 에도 그대로 적용됩니다. 데이터 형식 이름만 바꿔 부르면 됩니다. CSV든 요약이든, 결과물은 전부 내 노트북 안에 머뭅니다.

자주 만나는 막힘

증상	원인	대응
첫 호출이 timeout 처럼 멈춤	npm cache hydration (1~2분)	미리 `npm i -g @h6s-ai/cli` 로 글로벌 설치
`CREDENTIAL_NOT_FOUND`	자격증명 미등록 또는 provider 매칭 실패	`h6s_list_credentials` 로 등록 상태 확인
`INVALID_CREDENTIALS`	PFX 비밀번호 또는 ID/비번 오류	콘솔에서 자격증명 갱신
`failureCategory: CREDENTIAL`	등록은 됐지만 은행이 거부 (만료·이상로그인 등)	콘솔에서 자격증명 갱신 또는 재등록
응답이 비어 있음	해당 월에 거래가 없거나 계좌가 매칭되지 않음	`params.accountNumber` 명시해서 재시도

더 깊이

처음 한 번 받아보는 흐름을 더 차분히 따라가고 싶다면 재무 업무 자동화 빠른 시작 가이드에서 가장 작은 한 건부터 시작해 볼 수 있습니다.

Claude Code 통합 자체를 더 파고들 차례라면 Claude Code 연동 문서에 자격증명·데이터 형식·트러블슈팅이 한곳에 정리돼 있습니다.