// industry
1인 사장님 · 프리랜서
분기 부가세 · 종소세 자료를 직접. 세무사 없이도 신고서까지.
// schemas
사용 스키마
hometax.tax-invoices.sales.v1hometax.cash-receipts.sales.v1bank.transactions.cb.v1
// scenario
1인 사장님 — 분기 부가세 신고 자료
Claude Desktop 에 한 줄 — 지난 분기 매출/매입 세금계산서 + 현금영수증 4종이 신고서 항목별 합계로 정리되어 채팅창에 도착.
- 주기
- 분기 1회 (신고 ~1주 전)
- 대상
- 부가세를 직접 신고하는 1인 사업자 · 소상공인.
- 채널
- MCP
01사전 점검
아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.
API Key 가 있다 (MCP 설정 env 에 넣을 값)
echo $H6S_API_KEYh6s_live_... 로 시작하는 키가 출력된다
아니면 —
콘솔(https://h6s.ai)에서 발급 후 export H6S_API_KEY=h6s_live_...홈택스 자격증명이 등록돼 있다 (MCP 는 등록을 하지 않는다)
h6s credentials list홈택스에 매칭되는 공동인증서가 1건 이상 보인다
아니면 —
h6s credentials create --interactive --certCLI 가 글로벌 설치돼 있다 (MCP cold-start 회피)
h6s --version버전 문자열이 출력된다
아니면 —
npm i -g @h6s-ai/cli
02실행
클라이언트별 설정 파일을 toolkit 이 생성·병합한다. 한 번만.
npx @h6s-ai/toolkit install --target=cursor # 또는 --target=mcp | geminiClaude 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 timeoutnpx 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변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
자가 검증으로 이어가기
사전 점검 해줘CLI 단발 (CSV 저장)
h6s fetch hometax.tax-invoices.sales.v1 --provider HOMETAX --from 2026-01-01 --to 2026-03-31 --output csv --save vat-sales-Q1.csv// scenario
1인 사장님 — 종합소득세 월별 누적
매월 1일 Claude Code 가 전월 거래·세금계산서·현금영수증을 종소세 신고서 항목 기준 markdown 한 장으로 누적 정리.
- 주기
- 매월 1일
- 대상
- 5월 종소세 신고를 직접 하는 프리랜서·1인 사업자.
- 채널
- CLI · Claude Code
01사전 점검
아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.
CLI 가 설치돼 있다
h6s --version버전 문자열이 출력된다
아니면 —
npm i -g @h6s-ai/cli로그인(또는 API Key)이 돼 있다
h6s whoami워크스페이스와 사용량이 출력된다
아니면 —
h6s init # 또는 export H6S_API_KEY=h6s_live_...워크스페이스에 대상 자격증명이 있다
h6s credentials list공동인증서 또는 대상 기관 자격증명이 1건 이상 보인다
아니면 —
h6s credentials create --interactive --cert
02실행
이 한 줄로 끝. 수집 → 룰북·대사 → 외부 전송까지 internal-finance skill 이 오케스트레이션한다.
지난달 매출/매입/카드/현금 거래를 종소세 신고서 항목 기준으로 정리해서 income-tax-<YYYY-MM>.md 에 누적해줘.
내부적으로 도는 수집 명령: h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-04 + hometax.tax-invoices.sales.v1 / .purchase.v1 / cash-receipts.* --provider HOMETAX
03검증
- income-tax-<YYYY-MM>.md 한 장에 종소세 신고서 항목별 합계가 누적된다.
- 달이 바뀌면 같은 파일에 덧붙는다(월 1회 갱신).
04흔한 에러
CREDENTIAL_INSUFFICIENT_FOR_PROVIDER그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.
해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).
CERT_EXPIRED · CERT_WRONG_PASSWORD등록된 공동인증서가 만료됐거나 비밀번호가 틀렸다.
해결 h6s credentials update 로 갱신 후 재실행.
NO_API_KEYAPI Key 가 설정돼 있지 않다.
해결 h6s init 또는 export H6S_API_KEY=h6s_live_...
05변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
특정 달만 다시
2026-03 거래로 종소세 정리 다시 해줘매월 1일 자동화
github-action 의 cron 예시(월 1회)로 같은 프롬프트를 무인 실행// related