freee의 전표를 Claude Code로 모두 처리해봤습니다 [반두 플러그인으로 10분 설정]

자기 회사 전표 입력, 매달 귀찮지 않으신가요?

싱가포르에서 회사를 운영하고 있습니다. 일본 법인도 있기 때문에, 일본 쪽은 freee로 기장을 하고 있습니다.

매월 작업은 대략 이런 식입니다:

• 은행 명세서와 카드 명세서를 CSV로 다운로드
• 건별로 계정 과목을 선택하기
• 소비세 구분을 확인하기
• 전표 장부에 등록하기

월말이 되면, 이것만으로도 반나절에서 하루를 다 써버립니다. 자문 고객사가 여러 곳인 세무사님이라면 더 걸릴 겁니다.

'Claude Code로 자동화할 수 없을까?'라고 생각해서 시험해 봤습니다.

freee MCP를 사용해봤다

freee에는 공식 MCP 서버가 있습니다. Claude Code에서 freee API를 직접 호출할 수 있게 해주는 것입니다.

넣어봤습니다. 처음에는 순조로웠습니다.

'3월분 경비를 가져와 줘' → 제대로 데이터가 돌아옵니다. 오, 편리하다.

하지만, 여기서부터가 지옥이었습니다.

같은 오류에 3번이나 걸렸다

다음 날, 다른 작업을 하려고 했더니 이렇게 되었습니다.

company_id 불일치 에러

고쳤습니다. 이틀 후, 또 같은 에러입니다.

Claude Code는 매번 새로운 세션이라서, 지난번에 어떻게 고쳤는지 기억나지 않습니다. 매번 제로(0)부터 '어? 이거 무슨 에러였지?'를 해야 합니다.

다른 문제들도 걸렸습니다:

인증 토큰이 만료되었는데도, 에러 메시지가 '401'만 나온 경우 (무엇을 해야 할지 알 수 없음)

• API 요청 상한에 걸리는 경우 (freee는 1시간당 3600회가 상한. 배치 처리를 하면 초과함)
• 사업소 선택을 잊으면 데이터가 가져와지지 않는 경우 (초기 설정이 필요한데 문서에 쓰여 있지 않음)

모두 '알고 있으면 순식간에 회피할 수 있는' 종류의 문제입니다. 하지만 Claude Code는 모르기 때문에, 매번 같은 곳에서 멈춥니다.

에러 한 번당 3~5분의 손실. 월로 환산하면, 은근슬쩍 몇천 엔어치의 토큰이 녹아내리고 있었습니다.

반두 플러그인을 넣으니 모든 것이 해결됐다

같은 문제를 안고 있는 사람이 있나 찾아봤더니, X나 Zenn에서 비슷한 문제를 겪은 사람들을 많이 발견했습니다.

우선적으로, 자신을 위해 일본 회계의 시스템이나 전표 분류 데이터베이스를 학습시킨 후, Freee나 MF 등의 특이점을 KanseiLINK (SaaS의 AEO 기반)에서 가져와 반자동화함으로써 해결했습니다.

그 스킬을 비슷한 문제를 가진 경영자나 세무사 친구들에게 사용해 봤더니, 우리가 겪었던 문제들을 순조롭게 돌파했다고 호평받았기 때문에, **반두(番頭)**라는 Claude Code 플러그인을 만들어봤습니다.

일본 세무사 사무실을 위해 만들어진 회계 자동화 플러그인입니다.

우선 자기 회사 전표를 처리하기 위해 넣었더니, 아까까지의 문제들이 전부 사라졌습니다.

어떤 의미냐면:

문제	반두 없음	반두 있음
사업소 선택 누락	에러로 멈춤	처음에 자동으로 확인해 줌
...
특히 '수정 기억' 기능이 대단해서, 한 번 고치면 같은 패턴의 거래는 다시 틀리지 않습니다. 사용할수록 똑똑해져서, 수동으로 수정하는 횟수가 줄어듭니다.

제 지인의 경영자 및 세무사 8명에게 테스트를 받아봤더니:

• 도입 1개월 차: 약 60%가 자동 분류
• 2개월 차: 약 80%가 자동 분류
• 4개월 차: 약 90%가 자동 분류

나머지 10%만 확인하면 되기 때문에, 월말 전표 작업이 반나절 → 30분 정도로 줄었습니다.

설정 절차 (10분 만에 끝납니다)

방법① Claude Code에서 한 줄로 추가 (가장 쉬움)

Claude Code를 사용하는 분들은 이게 가장 빠릅니다. 터미널에서 아래를 실행하기만 하면 됩니다.

claude mcp add bantou -- npx -y @kansei-link/bantou@latest

이렇게 하면 Claude Code에 '반두'가 MCP 서버로 추가됩니다. 다음에 Claude Code를 실행하면, 전표 관련 툴이 자동으로 사용 가능해집니다.

freee API도 사용하고 싶다면, 환경 변수를 추가합니다:

claude mcp add bantou \
-e ANTHROPIC_API_KEY=your-api-key \
-e FREEE_ACCESS_TOKEN=your-freee-token \
...

방법② Claude Desktop / 다른 MCP 클라이언트에서 사용

방법② Claude Desktop / 다른 MCP 클라이언트에서 사용

Claude Desktop이나 Cursor처럼 MCP 설정 파일을 편집하는 유형의 클라이언트는 여기를 사용합니다.

설정 파일에 다음을 추가하세요:

{
"mcpServers": {
"bantou": {
...

freee API 연동도 사용할 경우, env에 다음을 추가해 주세요:

"FREEE_ACCESS_TOKEN": "your-freee-token",
"FREEE_COMPANY_ID": "your-company-id"

방법③ GitHub에서 클론 (내용을 보고 싶은 분)

git clone https://github.com/michielinksee/bantou.git
cd bantou/packages/claude-for-jp-accounting
npm install && npm run build

Apache-2.0 라이선스이므로 자유롭게 수정할 수 있습니다.

사용 방법: 자주 사용하는 명령어 3가지

1. CSV를 가져와 자동 분류

/bantou:import

은행 명세서나 카드 명세서의 CSV 파일을 전달하면 거래 내역을 자동으로 전표(仕訳)로 변환해 줍니다. freee, Yayoi(弥生), MF, TKC의 CSV 형식에 대응합니다.

계정 과목 판별은 3단계로 진행됩니다:

• 먼저 '전표 불필요 (대체/중복 등)' 항목을 제외하고 필터링합니다.
• 키워드와 과거 수정 기억으로 분류를 시도합니다.
• 그래도 판별할 수 없는 경우에만 AI에게 질문합니다.

2단계가 있기 때문에 API 비용(토큰 비용)이 상당히 절감됩니다. 모든 건을 AI에 던지는 방식과 비교했을 때 체감상 절반 이하입니다.

2. 분류를 수정하여 기억시키기

/bantou:correct

자동 분류 결과가 틀렸다면, 올바른 계정 과목을 알려주세요. 이 수정 사항은 로컬에 영구 저장됩니다.

예를 들어