headless

// local

1인 사장 부가세·종소세

세무사 없이 신고 자료를 직접 챙길 때. 분기 부가세·종소세 자료를 한 번에 받아 정리합니다.

// 상황

이런 상황이라면

신고가 막막하다

세무사 없이 부가세·종합소득세 자료를 챙기려면 어디서 뭘 받아야 할지부터 막힙니다.

자료가 흩어져 있다

매출 계산서, 현금영수증, 통장 내역이 따로 있어 모으는 데 시간이 듭니다.

누락이 무섭다

빠뜨린 자료가 있으면 신고가 틀어집니다.

// 흐름

어떻게 동작하나

  1. 01

    신고 자료 수집

    매출 세금계산서·현금영수증과 거래내역을 한 번에 받습니다.

  2. 02

    기간별 정리

    분기·연 단위로 자료를 모읍니다.

  3. 03

    신고에 활용

    정리된 자료를 신고나 상담에 그대로 씁니다.

// schemas

사용 데이터 형식

이 시나리오에서 받는 데이터입니다. 기관이 달라도 같은 모양으로 옵니다. 필드 전체 명세는 각 데이터 형식 문서에서 확인할 수 있습니다.

// 결과물

손에 남는 것

  • 부가세·종소세 자료를 한 번에
  • 매출·현금영수증·거래내역 통합
  • 분기·연 단위 정리
  • 누락 줄인 신고 준비

// 실행 가이드

그대로 따라 하면 됩니다

사전 점검부터 검증까지 이 페이지에서 끝납니다. 실행 방식이 여럿이면 하나만 고르면 됩니다.

01사전 점검

아래 명령을 붙여 넣어 현재 환경이 준비됐는지 확인합니다.

  • API Key 가 있다 (MCP 설정 env 에 넣을 값)

    echo $H6S_API_KEY

    h6s_live_... 로 시작하는 키가 출력된다

    대안으로 콘솔(https://h6s.ai)에서 발급 후 export H6S_API_KEY=h6s_live_...

  • 홈택스 자격증명이 등록돼 있다 (MCP는 등록을 하지 않는다)

    h6s credentials list

    홈택스에 매칭되는 공동인증서가 1건 이상 보입니다

    대안으로 h6s credentials create --interactive --cert

  • CLI가 글로벌 설치돼 있다 (MCP cold-start 회피)

    h6s --version

    버전 문자열이 출력됩니다

    대안으로 npm i -g @h6s-ai/cli

02실행

클라이언트별 설정 파일을 toolkit 이 생성·병합한다. 한 번만.

terminal
npx @h6s-ai/toolkit install --target=cursor   # 또는 --target=mcp | gemini

Claude Desktop은 --target=mcp 출력을 claude_desktop_config.json의 mcpServers에 병합하고 env 블록에 H6S_API_KEY를 넣는다. 등록 후 클라이언트 재시작.

등록이 끝나면 채팅창에 자연어 한 줄.

프롬프트

2026-Q1 부가세 신고용으로 매출/매입 세금계산서랑 현금영수증 4종 모아서 신고서 항목별로 합계 정리해줘.

이렇게 보이면 성공

✓ 2026-Q1 부가세 신고 자료 · 납부 예상 1,448,000원
매출 세금계산서 18건 24,300,000 / 매입 12건 9,820,000

03검증

  • 응답에 매출·매입 세금계산서 건수와 공급가액, 납부/환급 예상액이 나온다.
  • "표로 보여줘" 한 줄로 항목별 표가 펼쳐진다.
  • "사전 점검 해줘" 로 자가 검증 체크리스트로 이어진다.

04흔한 에러

MCP 서버가 연결 안 됨 / handshake timeout

npx cold-start (npm cache hydration) 가 handshake 보다 느리다.

해결 npm i -g @h6s-ai/cli 로 글로벌 설치 후 클라이언트 재시작.

도구 호출 시 NO_API_KEY 친절 에러

MCP 설정의 env 블록에 H6S_API_KEY 가 빠졌다.

해결 설정 파일 mcpServers.h6s.env 에 H6S_API_KEY 추가 후 재시작.

CERT_EXPIRED

등록된 홈택스 공동인증서가 만료됐다.

해결 h6s credentials update 로 인증서 갱신 후 다시 질의.

자격증명을 찾을 수 없음

MCP는 자격증명 등록을 다루지 않는다.

해결 CLI(h6s credentials create) 또는 콘솔에서 먼저 등록.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

자가 검증으로 이어가기

terminal
사전 점검 해줘

CLI 단발 (CSV 저장)

terminal
h6s fetch hometax.tax-invoices.sales.v1 --provider HOMETAX --from 2026-01-01 --to 2026-03-31 --output csv --save vat-sales-Q1.csv
전체 가이드 페이지로 보기

// 더 보기

관련 시나리오

income-tax-2026-04.zip

약 18 KB·월 1회 갱신

1인 사장님 종합소득세 월별 누적

매월 1일 Claude Code가 전월 거래·세금계산서·현금영수증을 종소세 신고서 항목 기준 markdown 한 장으로 누적 정리.

CLIClaude Code·매월 1일
team-finance
h

🔵 2026-Q1 부가세 사전 점검 · 환급 예상 매출세액 8,420,000 / 매입세액 9,180,000 → 환급 760,000 자가 검증: 음수세액 0건 · 추이 정상 · 사업자번호 일관 OK

부가세 사전 점검

분기 매출 · 매입 세금계산서 + 현금영수증 4종을 합산해 신고 예정 금액을 자가 검증. 누락 · 중복 · 금액 차이를 사전 발견.

CLI·분기 1회 (신고 ~1주 전)
cash-receipt-gap-2026-04.csv
입금일금액상대계좌현금영수증
2026-04-18330,000박**미발행 의심
2026-04-22150,000이**미발행 의심

현금영수증 발행 누락 탐지

은행 현금 입금 합 vs 홈택스 현금영수증 매출 합 비교. 발행 누락 의심을 탐지해 자진 발행 안내.

CLI·월 1회 (월초)

// faq

자주 묻는 질문

세무사 없이 가능한가요?

신고에 필요한 자료를 직접 받아 정리할 수 있습니다. 최종 신고 판단은 사용자 몫입니다.

무엇을 받나요?

매출 세금계산서, 매출 현금영수증, 은행 입출금내역을 함께 받습니다.

분기마다 다시 해야 하나요?

같은 수집을 분기마다 돌리면 됩니다. 자동화하면 손이 거의 들지 않습니다.

// related

함께 보면 좋은 흐름

같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.

headless

첫 수집은 작게 시작합니다

가입하고 API 키를 만드세요. 짧은 기간의 데이터로 응답 형식을 먼저 확인할 수 있습니다.

무료로 첫 수집 시작