jp-payroll-mcp

일본 급여, 사회보험 및 노동법을 조회가 아닌 계산으로 처리합니다. 47개 도도부현 전체의 보험료, 원천징수세, 표준보수 결정 및 개정, 휴가 면제, 최저임금 — 각 답변이 근거하는 법령 또는 후생노동성 고시까지 함께 제공합니다.

공표된 표와 셀 단위로 대조 검증: 모든 변경 시 3,638개의 검증을 통과합니다.

두 가지 사용 방법

MCP 서버로 — AI 어시스턴트를 통해 질문하는 방식. 17개 도구, 무료, 키 불필요:

claude mcp add jp-payroll -- npx -y jp-payroll-mcp

HTTP API로 — 소프트웨어에 통합하는 방식. 36개 엔드포인트, OpenAPI 3.0, 배치 지원:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&birth_date=1986-04-01"

MCP 서버는 API 위의 얇은 계층이므로 둘 다 동일한 답변을 제공합니다. 어떤 것을 선택할지는 사람이 질문하는지 프로그램이 질문하는지에 따라 달라집니다.

• MCP 서버 소스 및 자체 README: mcp/ · 일본어

• 실시간 API: https://japan-payroll-api.tsumugi.workers.dev

• OpenAPI 스펙: /openapi.json

Related MCP server: taiwan-payroll

관련 도구

일본 법정 MCP 서버는 대부분 조회 방식입니다. 법률 텍스트를 전달하고 해석은 사용자에게 맡깁니다. 이 서버는 계산을 수행하고, 근거가 된 조항을 반환합니다. 경쟁 관계가 아니라 보완 관계입니다:

이미 그중 하나를 사용 중이라면, 이 서버를 함께 추가하세요. 둘 다 갖춘 어시스턴트는 질문에 따라 적절한 도구를 선택합니다.

왜 필요한가

• 통합 API가 없습니다. 개발자들은 協会けんぽ, 厚生労働省, 각 도도부현 노동국에서 개별적으로 자료를 수집해야 합니다.

• 규칙이 까다롭습니다. 보험료는 실제 급여가 아닌 표준보수 (50등급 계단 함수)를 기준으로 계산됩니다. 단, 고용보험은 실제 급여를 사용합니다. 연금은 32등급에서 상한이 적용됩니다. 개호보험은 40~64세에만 적용됩니다. 근로자 부담분은 반올림 (0.50엔 이하 절사)됩니다. 이 중 하나라도 틀리면 그럴듯해 보이지만 틀린 숫자가 나옵니다.

MCP 서버

소스는 mcp/에 있으며, 자체 README · 일본어가 있습니다. npm run mcp:test로 테스트할 수 있습니다. 실제 MCP 클라이언트로 실제 stdio 전송을 구동합니다. 핸들러가 고장난 도구도 목록에는 정상적으로 표시되고 호출될 때만 실패하기 때문입니다.

MCP 서버는 무료이며 앞으로도 무료입니다. 수익 채널이 아닌 배포 채널입니다. npm은 비용이 들지 않고 MCP에는 자체 과금이 없습니다. 이는 의도적인 선택입니다. 문제는 RapidAPI가 이미 처리하는 과금이 아니라 발견 가능성이었고, 일본 법정 데이터 트래픽이 실제로 몰리는 곳이 MCP이기 때문입니다.

엔드포인트

prefecture는 영문 이름 (Tokyo, 대소문자 무시), 일본어 (東京 또는 東京都), 또는 JIS 코드 (13)를 허용합니다.

가장 중요한 호출

직원 한 명의 급여 계산은 단일 요청으로 처리됩니다:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40&dependants=2"

gross                    350,000
social insurance          -55,750
                       ----------
after social insurance   294,250   <- the base withholding tax is charged on
withholding income tax    -4,480
                       ----------
net pay                  289,770

그 중간 줄이 핵심입니다. 소득세는 총급여가 아니라 사회보험 이후 급여에 부과되며, 이를 수작업으로 계산하는 것이 이 엔드포인트가 막고자 하는 실수입니다. 응답에는 결정된 등급, 근로자와 사용자 부담분으로 나뉜 모든 보험료, 그리고 세금이 산출된 구간도 포함되어 있어, 계산 결과를 신뢰하는 대신 검증할 수 있습니다.

주민세(住民税)는 지방자치단체가 부과하고 사용자에게 통지하므로, 어떤 API도 이를 계산할 수 없습니다. resident_tax=를 전달하면 순급여에서 차감됩니다.

income_tax=false를 전달하면 사회보험만 계산됩니다.

통합 전 확인 사항

• GET /v1/enums는 허용되는 모든 값(business_type, column, calendar)과 모든 오류 코드를 나열하므로, 400 응답에서 발견하는 대신 빌드 시점에 확인할 수 있습니다.

• 오류에는 안정적인 code가 포함됩니다. invalid_request와 missing_parameter는 호출을 수정해야 함을 의미하고, out_of_coverage는 입력이 유효하지만 게시된 범위를 벗어났음을 의미하므로 다른 분기가 필요합니다. 영어 문구에 의존하지 마세요. 변경될 수 있습니다.

• GET /v1/data-freshness는 각 데이터셋의 최신 상태를 알려줍니다.

데이터

모든 수치는 공식 스프레드시트에서 프로그래밍 방식으로 추출되며, 수작업으로 옮겨 적지 않습니다. 추출기는 scripts/에서 확인하세요.

법령을 사용하지 않는 이유

소득세 수치는 e-Gov 법령 API를 통한 所得税法이 아니라 국세청이 공표한 표에서 가져옵니다. 법령 버전에는 2.1% 재건 부가세가 누락되어 있기 때문입니다. 105,000~107,000엔 구간에서 乙열은 別表第二 기준 3,700엔이지만 실제로는 3,800엔입니다. 105,000엔 미만에서는 3.063%가 아닌 3%입니다. 급여 계산에 법령은 잘못된 출처입니다.

740,000엔을 초과하면 표는 더 이상 표가 아닙니다. 한계세율이 적용되는 기준점이 됩니다. 이 기준점들은 동일선상에 있지 않습니다. 각각에 반올림이 내재되어 있으므로, 재계산하지 않고 공표된 기준값을 그대로 사용합니다. 乙열에는 甲열의 9개와 달리 기준점이 2개(740,000과 1,710,000)뿐이며, 甲열 기준점에서 乙열 초과분을 측정하면 조용히 과소 부과됩니다. 이는 실제로 발생했던 버그였으며, 셀 단위 비교로 발견되었습니다.

인용은 실제 조문으로 확인됩니다

법령 이름만 언급하고 독자가 직접 찾게 하는 것은 절반만 답한 것입니다. 이 API가 인용하는 모든 조항이 번들로 포함되어 있으므로, 健康保険法第43条를 같은 왕복 요청에서 실제 조문으로 변환할 수 있습니다.

curl 'https://japan-payroll-api.tsumugi.workers.dev/v1/statute?ref=健康保険法第43条'
curl '…/v1/standard-remuneration/revision?…&include=statute_text'

실제로 인용은 다양한 방식으로 작성되며 모두 해석됩니다 — 健保法43条, 厚年法81条の2, 徴収法11条, 第 누락, 항 단위 참조, 전각 숫자 등. e-Gov의 약어는 실무자들이 사용하는 방식과 다릅니다(e-Gov는 厚生年金法이라고 부르지만 모두 厚年法이라고 씁니다). 따라서 두 가지 모두 허용됩니다.

조문 텍스트는 요청 시점이 아니라 빌드 시점에 e-Gov 法令API에서 가져옵니다. 모든 요청에서 e-Gov를 호출하면 e-Gov가 중단될 때 이 API도 중단되기 때문입니다. scripts/extract-statutes.py에 조항 목록이 하나로 관리되며, 테스트 스위트는 코드가 생성하는 모든 인용이 해석되는지 확인합니다. 뒷받침할 조항 없이 추가된 인용은 조용히 빈 결과를 반환하는 대신 빌드를 실패시킵니다.

알려진 한계

• 연말정산 표는 포함되지 않습니다. 令和8年分의 「給与所得控除後の給与等の金額の表」는 2026-08 기준 아직 공표되지 않았습니다. 국세청은 9월경에 공표합니다. 令和8年度税制改正은 또한 2026-12-01부터 근로소득 공제 최저액을 740,000엔으로 인상하므로 해당 표도 변경됩니다.

• FY2026 최저임금은 포함되지 않습니다. 2026-08 기준, 개정이 도도부현별로 진행 중이며 2026년 10월부터 시행됩니다. API는 현재 시행 중인 FY2025 요율을 제공합니다. 47개 도도부현이 모두 공표하면 갱신해야 합니다.

• 고용보험 이력은 FY2026만 포함됩니다. 이전 연도는 1차 출처로 검증되지 않았으므로, 추측 대신 생략합니다.

• 주민세는 범위 밖입니다. 주민세는 전년도 소득과 지방자치단체에 따라 달라지며, 사용자가 계산하는 것이 아니라 지방자치단체가 부과하므로, /v1/payroll은 전달된 금액을 차감할 뿐 직접 산출하지 않습니다.

• 판정 엔드포인트는 신고 대상 여부를 판단할 뿐, 신고 자체는 아닙니다. 여러 규칙은 API가 확인할 수 없는 사실에 의존합니다 — 계절적 변동이 「業務の性質上例年発生することが見込まれる」에 해당하는지, 수당이 実費弁償인지, 근로자가 동의했는지 등입니다. 이러한 항목은 선언된 입력값으로 응답에 그대로 반영되며, 보험자는 保険者算定에 따라 다른 결론을 내릴 수 있습니다.

• 모든 표준보수 경로가 지원되는 것은 아닙니다. 資格取得時決定은 결정의 유효 기간을 반환하지만 초기 報酬月額은 계산하지 않습니다(健保法42条1項에는 네 가지 방법이 있으며, 그중 세 가지는 다른 근로자에 대한 수치가 필요합니다). 二以上事業所勤務 — 여러 사용자의 보수를 합산하고 보험료를 분담하는 경우 — 는 전혀 구현되지 않았습니다. 3개월 기간 내에 고정급여가 두 번 변경될 때 발생하는 기준점 재설정도 구현되지 않았습니다.

• 일부 실무 사항은 1차 문서로 출처를 확인할 수 없어 단정하지 않고 응답에 guidance.fixed_pay.unverified로 표시됩니다: 家族手当이 고정급여에 포함되는지, 유급휴가가 支払基礎日数에 어떻게 산정되는지, 年俸制가 어떻게 처리되는지 등입니다. 2차 출처는 세 가지 모두에 대해 일치하지만, 정부 부처는 문서로 명시하지 않는 것으로 보입니다.

검증

test/verify.mjs는 라이브 서버에 대해 3,638개의 단언을 실행합니다. 핵심은 API가 계산한 보험료를 250개 도도부현 × 등급 조합에 대한 공식 協会けんぽ 워크북에 인쇄된 금액과 비교하는 것입니다 — 공표된 절반 부담액이며, 공식의 재구현이 아닙니다. 또한 다음을 확인합니다:

• 등급 경계의 연속성, 경계의 엔 단위 값이 상위 등급에 속하는지

• 1등급과 32등급에서의 연금 상한 고정

• 40세에 개시되고 65세에 종료되는 개호보험 전환

• 다른 보험료가 등급을 사용하는 동안 고용보험은 실제 급여에 부과되는지

• 시점별 최저임금(시행일 전날 포함)

• 네 가지 입력 형식 모두에서 도도부현 해석

• 47개 도도부현 모두 유효한 급여 응답 반환

• 독립적으로 계산된 참조값과 영업일 수 비교

• 2026-09-22 国民の休日(다른 두 공휴일 사이에 있어서만 공휴일인 날)

• 일회성 황실 공휴일: 大喪の礼, 即位礼正殿の儀, 結婚の儀

• NTA PDF의 계산 예시와 법인번호 검증번호 비교, 동일한 기준 번호에 대해 다른 모든 검증번호가 거부되는지

• 원천징수세 표의 모든 공표 셀 — 231개 구간 × 8개 甲열 + 乙열, 2,079개 수치를 국세청 자체 워크북과 비교

• 통과하는 인보이스 검증번호가 법인으로 귀속되지 않는지: 개인사업자도 동일한 규칙을 충족하므로 번호만으로 소유자를 추론할 수 없음

• 日本年金機構가 공표하는 8개 단일 등급 随時改定 사례 — 건강보험 4개, 연금 4개 — 각각 표에 명시된 표준보수에 도달하는지, 실제 등급과 구현이 사용하는 확장 척도 모두에서

• 건강보험과 연금이 독립적으로 판정되는지: 연금 상한을 초과하는 인상이 건강보험 6등급을 이동시키고 연금 등급은 전혀 이동하지 않음

• 15일 定時決定 폴백이 短時間就労者에게만 적용되고 다른 사람에게는 적용되지 않는지, 그리고 随時改定에서는 어떤 경우에도 적용되지 않는지

• 모든 폐쇄 값 집합이 /v1/enums에 나타나는지, 그래서 통합자가 타입을 생성하는 엔드포인트에 도달하지 않고는 새 enum을 출시할 수 없음

npx wrangler dev --port 8799
node test/verify.mjs

# or against production
BASE=https://japan-payroll-api.tsumugi.workers.dev node test/verify.mjs

개발 / 배포

npm install
npx wrangler dev
npx wrangler deploy

데이터는 번들에 포함되어 있으므로(~40KB gzip), 데이터베이스, KV, 콜드 스타트가 없습니다.

응답에는 Cache-Control: public, max-age=3600, stale-while-revalidate=86400이 포함됩니다. 하루가 아닌 한 시간인 이유는 요율이 정해진 날짜에 변경되고 수정 사항이 당일 호출자에게 도달해야 하기 때문입니다. stale-while-revalidate는 그 뒤에서 갱신이 진행되는 동안 응답을 즉시 유지합니다. workers.dev 응답은 Cloudflare 자체 엣지에서 캐시되지 않습니다 — 모든 요청이 Worker를 호출합니다. 사용자 지정 도메인을 사용하면 그만한 가치가 있을 때 엣지 캐싱을 활성화할 수 있습니다.

일본에서 배포된 Worker를 대상으로 측정: 왕복 중앙값 65ms, 최대 83ms; gzip은 50등급 표를 6,841바이트에서 1,041바이트로 줄입니다.

유지보수

법정 수치는 정해진 날짜에 변경되며, 개정을 놓친 API는 더 이상 사실이 아닌 숫자로 계속 응답합니다. 두 가지 메커니즘이 이를 방지합니다.

API가 자체 최신 상태를 보고합니다. GET /v1/data-freshness는 각 데이터셋의 적용 범위와 다음 변경 예정 시기를 명시하며, 주요 데이터 응답에는 freshness 마커가 포함됩니다. 모니터링이 실패하더라도 호출자는 오래된 수치를 확인할 수 있습니다.

주간 작업이 출처를 감시합니다.

npm run watch          # fingerprints each source, alerts Discord on change
npm run watch:dry      # same, without notifying

두 가지 독립적인 항목을 확인합니다. 하나만으로는 공백이 남기 때문입니다: 소스 파일의 해시와 Last-Modified(조용한 재발행 감지), 그리고 달력(부처가 새 URL에 개정판을 게시하고 기존 URL을 그대로 두는 경우 감지). 알림에는 이 저장소를 가리키는 대신 해당 데이터셋에 대한 정확한 명령이 포함됩니다. 알림은 몇 달 후에, 대개 이 저장소의 구조를 잊어버린 사람이 읽습니다.

필요해지기 전에 추출기를 연습하세요. 최저임금 추출기는 --check를 지원하며, 이는 아무것도 쓰지 않고 전체 추출을 실행하여 현재 배포된 데이터와 비교합니다:

curl -L -A "Mozilla/5.0" -o mw.xlsx https://www.mhlw.go.jp/content/11200000/001571219.xlsx
python scripts/extract-minimum-wage.py --check

출력이 일치한다고 표시되어야 합니다. 회계연도가 변경되지 않았는데 일치하지 않는다면 추출기와 배포된 데이터가 분기된 것입니다. 이는 새 수치가 발표되는 날 스크립트가 생성하는 것을 그대로 배포하고 싶은 유혹이 생길 때 발견하는 것보다 8월에 알아두는 것이 좋습니다.

주간 실행으로 등록하세요:

powershell -ExecutionPolicy Bypass -File scripts
egister_watch_task.ps1

유료 경로 검증

테스트 스위트는 RapidAPI의 유료 플랜이 전체 크기 배치를 받는지 확인할 수 없습니다. 그러려면 RapidAPI가 발급하는 프록시 시크릿이 필요한데, 테스트에 있는 시크릿은 시크릿이 아닙니다. 수익에 중요한 절반을 확인합니다 — 시크릿이 없는 호출자가 헤더를 설정하여 유료 플랜을 주장할 수 없는지.

권한 변경 후 로그에서 나머지 절반을 확인하세요:

npx wrangler tail --format json

RapidAPI 플레이그라운드에서 아무 엔드포인트를 호출하고 요청 라인을 확인하세요. 구독 이름이 표시되어야 합니다:

{"channel":"rapidapi","path":"/","status":200,"plan":"BASIC"}

plan이 있으면 프록시 시크릿이 일치한다는 뜻입니다. rapidapi 요청에서 plan: null이면 일치하지 않는다는 뜻입니다 — 그리고 모든 유료 고객이 요금을 부과받으면서 무료 티어 한도로 서비스되고 있다는 의미입니다. 그 실패는 외부에서 보이지 않으므로, 불만을 기다리기보다 의도적인 확인을 할 가치가 있습니다.

중요한 날짜

데이터셋을 새로고침한 후에는 src/data/freshness.json을 업데이트하고 npm run rapidapi:prepare를 실행하여 라이브 API가 다시 검증되고 OpenAPI 스펙이 재생성되도록 하세요.

게시 파이프라인

각 API는 recipes/<slug>/recipe.py 아래의 레시피입니다 — 엔드포인트는 거기에 한 번만 선언되며, OpenAPI 스펙과 RapidAPI 목록 텍스트가 모두 그로부터 생성됩니다.

npm run rapidapi:prepare

그 명령은 모든 레시피에 대해 다음을 수행합니다:

1. 레시피를 검증하고,

2. 라이브 API의 모든 선언된 엔드포인트를 호출하여 파싱 가능한 JSON과 함께 200을 요구합니다 — 필수 파라미터가 있는 엔드포인트의 경우, 파라미터가 누락되면 400을 요구합니다. 이것이 recipe.py와 src/index.ts 사이의 드리프트를 잡아내는 방법입니다,

3. build/openapi/<slug>.openapi.json을 작성하고,

4. 목록 URL, 스펙 경로, 붙여넣을 정확한 값을 포함한 Discord 알림을 보냅니다.

목록 등록 자체는 수동입니다. https://rapidapi.com/provider/<id>/new의 Add-API 양식은 reCAPTCHA v3로 보호되므로 최종 제출은 사람이 합니다 — 세 개의 필드, "Specify using: OpenAPI" 선택, 생성된 스펙 업로드. API당 약 2분이 소요되며, 주 1~2회의 게시 주기에는 병목이 되지 않습니다.

알림이 실제로 도착하려면 .env에 DISCORD_WEBHOOK_URL을 설정하세요 (.env.example 참조). 설정하지 않으면 메시지는 콘솔에만 출력됩니다.

브라우저 세션

npm run rapidapi:login은 실제 Chrome 창을 열어 직접 로그인하게 합니다 — 스크립트는 비밀번호를 절대 볼 수 없습니다. 세션은 rapidapi_profile/에 유지됩니다 (gitignore됨). 세션이 만료되면 다시 실행하세요.

운영 안전

• state/pipeline.halt.json은 사람이 제거할 때까지 모든 것을 중지합니다. set_halt()는 세션이 죽을 때 호출되고, clear_halt()는 재로그인 성공 시 호출됩니다.

• pipeline/rapidapi/config.py의 MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH는 게시 속도를 사람 수준으로 유지합니다.

라이선스 및 출처 표시

기본 데이터는 공공데이터이용규약(제1.0판)에 따른 일본 정부 공개 데이터로, 상업적 이용과 출처 표시를 조건으로 한 재배포를 허용합니다. 모든 응답에는 출처를 명시하는 attribution 블록이 포함됩니다.

본 서비스는 어떤 일본 정부 기관의 보증도 받지 않았습니다. 법정 신고에 활용하기 전에 공식 출처와 대조하여 확인하세요.