Claude Code 에서 5분 만에 거래내역 받아오기

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

이 글은 노트북 앞에서 따라 할 수 있는 단계별 가이드다. 처음 셋업이라면 약 10분, 다음번부터는 한 줄.

무엇을 만들 것인가

끝에 손에 쥐는 그림은 이렇다. Claude Code 안에서:

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

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

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

1. Claude Code 가 h6s_fetch_data MCP 도구를 호출한다 (provider=CB_KB, schema=bank.transactions.cb.v1, month=2026-04).
2. headless 백엔드가 국민은행에서 거래내역을 받아 표준 데이터 형식에 맞춰 돌려준다.
3. ContractRecord 배열이 Claude Code 로 돌아온다.
4. Claude Code 가 필요한 집계와 자연어 요약을 만든다.

여기까지 가는 데 필요한 준비물 세 가지.

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

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

h6s.ai 에서 회원가입 후 콘솔로 들어간다. API Keys 메뉴에서 새 키를 발급하면 h6s_live_ 로 시작하는 문자열이 나온다. 즉시 사용 가능하다.

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분)

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

> 지난달 국민은행 거래내역 받아줘

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

{
  "schemaId": "bank.transactions.cb.v1",
  "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) 에도 그대로 적용된다. 데이터 형식 이름만 바꿔 부르면 된다.

자주 만나는 막힘

더 깊이

첫 호출이 잘 됐다면 다음은 Claude Code 통합을 더 파고들 차례다. Claude Code 연동 문서에 자격증명·데이터 형식·트러블슈팅이 한곳에 있다.