매출 세금계산서를 장부에 옮길 때는 자료 수집과 분개 규칙을 나눠 봐야 합니다. 수집은 자동화해도 계정과목과 세금 처리는 회사 규칙에 따라 검토해야 합니다.

이 가이드는 Cursor에 headless MCP를 연결해 매출 세금계산서를 받고, 예시 분개 스크립트로 전표 후보를 만드는 순서를 보여 줍니다. 예시 규칙은 실제 장부 규칙과 대조한 뒤 사용합니다.

누가 이 글을 읽으면 좋을까

부가세·결산 때 세금계산서를 수기로 분개해 회사 장부에 올리는 회계 담당
경리 시스템에 분개 자동화를 붙이려는 개발자
사전 지식: Cursor, headless 계정, 분개 대상 사업자의 공동인증서

무엇을 만들 것인가 (미리보기)

Cursor 채팅에서:

지난달 매출 세금계산서 받아서 분개 전표로 끊어줘

# 잠시 후 …
세금계산서 23건 → 전표 23건.
2026-04-30 ㈜에이클라이언트  (차) 외상매출금 1,100,000 / (대) 제품매출 1,000,000, 부가세예수금 100,000
…
journal-2026-04.csv 로 저장 완료.

받은 데이터는 회사 회계 시스템에 그대로 넣을 전표 형태입니다. 외부로 내보낼 필요 없이 결산 자료로 바로 씁니다.

1. 준비

headless 콘솔에서 API key를 발급하고, 분개 대상 사업자의 공동인증서를 한 번 등록합니다. 인증서 한 건이면 홈택스가 자동으로 매칭됩니다.

bash

export H6S_API_KEY=h6s_live_...

2. Cursor에 MCP 연결하기

Cursor의 MCP 설정에 headless 진입점을 추가합니다. ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "h6s": {
      "command": "npx",
      "args": ["-y", "@h6s-ai/cli", "mcp"],
      "env": { "H6S_API_KEY": "h6s_live_..." }
    }
  }
}

Cursor를 한 번 재시작하면 h6s_* 도구가 채팅에서 자연어로 호출됩니다. 첫 호출은 npm cache를 채우느라 1~2분 걸릴 수 있습니다. 미리 npm i -g @h6s-ai/cli 로 깔아두면 이 대기를 건너뜁니다.

3. 세금계산서 받기

매출 세금계산서의 데이터 형식 ID는 hometax.tax-invoices.sales.v1 입니다. 35개 필드가 고정이라 분개에 필요한 것만 골라 쓰면 됩니다 - 작성일자, 공급가액, 세액, 합계금액, 거래처 상호·사업자번호. 전체 필드는 /schemas/hometax.tax-invoices.sales.v1 응답에서 확인합니다.

Cursor에 자연어로 부탁하면 내부에서 h6s_fetch_data 가 호출됩니다.

지난달 매출 세금계산서 받아줘

4. 분개 스크립트

받은 세금계산서를 회사 계정과목 규칙에 맞춰 전표로 바꿉니다. 핵심은 규칙 한 덩어리와 매핑 한 덩어리입니다.

typescript

import { writeFileSync } from "node:fs";

type TaxInvoice = {
  writeDate: string;                // 작성일자
  supplyAmount: number;             // 공급가액
  taxAmount: number;                // 세액
  totalAmount: number;              // 합계 금액
  buyerOrganizationName: string;    // 공급받는자(거래처) 상호
  buyerBusinessIdentifier: string;  // 공급받는자(거래처) 사업자등록번호
};

type Line = { account: string; debit: number; credit: number };

// 회사 규칙: 외상매출 기준. 현금매출이면 차변 계정만 바꾼다.
function toJournal(inv: TaxInvoice): Line[] {
  return [
    { account: "외상매출금", debit: inv.totalAmount, credit: 0 },
    { account: "제품매출", debit: 0, credit: inv.supplyAmount },
    { account: "부가세예수금", debit: 0, credit: inv.taxAmount },
  ];
}

function assertBalanced(lines: Line[]) {
  const d = lines.reduce((s, l) => s + l.debit, 0);
  const c = lines.reduce((s, l) => s + l.credit, 0);
  if (d !== c) throw new Error(`차대 불일치: ${d} vs ${c}`);
}

async function main() {
  const raw = await fetch("https://api.h6s.ai/api/v1/data-jobs/" + process.env.JOB_ID + "/results", {
    headers: { Authorization: `Bearer ${process.env.H6S_API_KEY}` },
  }).then((r) => r.json());

  const rows: string[] = ["date,counterparty,account,debit,credit"];
  for (const inv of raw.data as TaxInvoice[]) {
    const lines = toJournal(inv);
    assertBalanced(lines);
    for (const l of lines) {
      rows.push(
        [inv.writeDate, inv.buyerOrganizationName, l.account, l.debit, l.credit].join(","),
      );
    }
  }
  writeFileSync("journal.csv", rows.join("\n"));
}

main();

assertBalanced 로 전표마다 차변 합과 대변 합을 맞춰봅니다. 분개 자동화에서 가장 자주 깨지는 지점이라 루프 안에서 매번 확인합니다. 회사 장부에 올리기 전에 검증을 한 단계 거치는 셈입니다.

회사마다 계정과목이 다르니 toJournal 하나만 회사 규칙으로 바꾸면 됩니다. 현금매출·면세·영세율은 분기 한 줄로 나눠 처리합니다. 이 규칙을 Cursor에 말로 설명하면 함수 본문을 대신 고쳐줍니다.

5. 자주 만나는 막힘

증상	원인	대응
도구가 안 보임	MCP 등록 후 미재시작	Cursor 재시작
첫 호출이 멈춤	npm cache hydration	`npm i -g @h6s-ai/cli` 선설치
`failureCategory: CREDENTIAL`	인증서 만료·미등록	콘솔에서 자격증명 갱신
차대 불일치 예외	면세·영세율을 일반 규칙으로 처리	`toJournal` 에 과세유형 분기 추가
거래처 누락	수정세금계산서·합계표 혼입	매출분(`sales.v1`)만 받는지 확인

더 깊이

분개가 한 번 끊기기 시작했다면, 규칙 분기를 사람이 다 짜는 대신 AI에게 맡기는 쪽으로 넘어갈 수 있습니다. 매출·면세·영세율 판정을 LLM이 추론해 전표를 끊는 흐름은 AI 자동 분개로 회사 장부 채우기에서 이어집니다.

같은 headless API를 다른 에이전트에서 쓰는 방법은 Cursor 연동 문서에 설치·자격증명·트러블슈팅과 함께 정리되어 있습니다.