// 업종별 — 그대로 따라가는 시나리오

1인 사장님 — 분기 부가세 신고 자료

Claude Desktop 에 한 줄 — 지난 분기 매출/매입 세금계산서 + 현금영수증 4종이 신고서 항목별 합계로 정리되어 채팅창에 도착.

MCP분기 1회 (신고 ~1주 전)

이런 분께 — 부가세를 직접 신고하는 1인 사업자 · 소상공인.

MCP · Claude

2026-Q1 부가세 신고용 자료 모아줘

매출 세금계산서 18건 · 공급가액 24,300,000

매입 세금계산서 12건 · 공급가액 9,820,000

신고 예정 납부세액 1,448,000▍

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

클라이언트별 설정 파일을 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

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) 또는 콘솔에서 먼저 등록.

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

자가 검증으로 이어가기

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