The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MCP Jp Paid Leave listing page.
An MCP (Model Context Protocol) server for calculating Japan's statutory annual paid leave ("nenkyu") under the Labor Standards Act: entitlement grants, attendance-rate checks, proportional grants for part-time workers, carryover/prescription, and the 5-day mandatory-use rule. It lets MCP-capable clients such as Claude Desktop invoke these calculations directly.
No network access is used at runtime. All statutory rules are embedded as constants in the code.
apply_company_policy.basis field:
"legal_minimum": the statutory minimum value"company_policy_applied": the value after applying a company policy (only from apply_company_policy)apply_company_policy automatically corrects
it to the statutory minimum and returns a warning.meta field with
the effective date and source URL of each rule actually used, the date the data was last verified
(dataVerifiedOn), and a staleness warning when applicable. See
Versioning policy and Maintenance policy below.| Tool | Description |
|---|---|
calculate_entitlement | Computes the grant date and number of days for a given grant occurrence, from hire date and reference-date method |
check_attendance_rate | Checks whether the 80% attendance-rate requirement is met, with a numerator/denominator breakdown |
list_grant_schedule | Lists the grant schedule for a given number of years from the hire date |
proportional_entitlement | Computes the proportional grant for part-time workers, based on weekly/annual scheduled working days |
calculate_carryover | Computes carryover, forfeiture under the 2-year prescription period, and remaining balance |
check_mandatory_five_days | Determines whether an employee is subject to the mandatory 5-day rule, and reports compliance status |
apply_company_policy | Applies a company policy on top of the statutory minimum, correcting and warning if it falls short |
Give the hire date (hireDate) and which grant occurrence to compute (grantNumber: 1 = the first grant
at 6 months of service, 2 = the second grant at 1 year 6 months, etc.).
referenceDateMethod: "individual" (the statutory default — each employee's own basis date) or
"uniform" (a company-wide unified basis date, i.e. "seiitsu-teki toriatsukai")uniformBasisMonthDays: required when uniform is used — an array of "MM-DD" candidate basis dates
(e.g. ["04-01"] or ["04-01","10-01"])weeklyScheduledDays / annualScheduledDays / weeklyScheduledHours: optional, for proportional
grants (part-time workers)For the uniform method, the server correctly computes the recurring chain: once the first front-loaded
basis date is found, every subsequent grant recurs on the same month/day each year. Any period shortened
by front-loading is returned as shortenedPeriod, with a note that this period must be treated as fully
attended for attendance-rate purposes (when calling check_attendance_rate, count it as ordinary worked
days in actualWorkedDays etc. rather than as absence — don't carve it out as unattended).
Returns an error if the statutory basis date (statutoryBasisDate, not the hire date) falls before
2001-04-01. The current grant-days table (introduced by Act No. 112 of 1998) took effect for most
purposes on 1999-04-01, but a transitional schedule with lower figures for certain tenure brackets applied
through 2001-03-31. This tool does not implement that transitional schedule, so 2001-04-01 (once the
transition was fully complete) is the verified floor (see Versioning policy and
CHANGELOG.md).
This floor applies to each grant's own basis date, not to the hire date. No matter how old the hire date is, a specific grant computes fine as long as that grant's basis date is on or after 2001-04-01. For example, for an employee hired in 1995, computing "the most recent grant as of 2026" (the 31st grant, basis date 2025-10-01) succeeds. Only grants whose own basis date is before 2001-04-01 (e.g. that same employee's 1st grant, basis date 1995-10-01) return an error.
Checks the "80% of all working days" requirement for entitlement.
Design principle: deciding whether a given day belongs in the numerator or is excluded from the
denominator is exactly the value this tool should provide — and exactly where humans and AI callers are
most likely to get it wrong. So the caller does not classify anything. Instead, break the period down into
the following 11 day-count fields and pass them as-is (all required except asOfDate — if a category
doesn't apply, pass 0 explicitly; omitting a field is an error, not an assumed zero):
| Argument | Meaning |
|---|---|
scheduledWorkingDays | Total scheduled working days for the period (days with a work obligation; excludes scheduled days off) |
actualWorkedDays | Days actually worked |
paidLeaveTakenDays | Days of annual paid leave taken |
workInjuryOrIllnessLeaveDays | Days on leave for a work-related injury or illness |
maternityLeaveDays | Days of maternity leave (Labor Standards Act Article 65) |
childcareOrFamilyCareLeaveDays | Days of childcare or family-care leave |
employerCausedSuspensionDays | Days suspended for reasons attributable to the employer (including employer-caused management/operational-obstacle suspension) |
lawfulLaborDisputeDays | Days with no work provided due to a lawful strike/labor dispute |
forceMajeureSuspensionDays | Days suspended due to force majeure |
workedOnScheduledDayOffDays | Days worked on what was originally a scheduled day off — not included in scheduledWorkingDays |
otherAbsenceDays | Ordinary absence not covered by any category above (unauthorized absence, personal illness, etc.) |
scheduledWorkingDays must equal the sum of the other 9 fields (everything except
workedOnScheduledDayOffDays). A mismatch is an error — the tool never guesses at a reconciling number.
Based on Labor Standards Act Article 39 paragraph 10 / Article 65, Directive Hakki No. 17 (Sept. 13, 1947), and Directive Kihatsu 0710 No. 3 (July 10, 2013), the tool classifies each field into one of four treatments internally:
actualWorkedDays, paidLeaveTakenDays, workInjuryOrIllnessLeaveDays,
maternityLeaveDays, childcareOrFamilyCareLeaveDaysotherAbsenceDaysemployerCausedSuspensionDays,
lawfulLaborDisputeDays, forceMajeureSuspensionDays (Kihatsu 0710 No. 3, Section 1-3)workedOnScheduledDayOffDays
(Kihatsu 0710 No. 3, Section 1-1)The result's breakdown.classification always includes each field's day count, its resulting treatment,
and the specific legal basis (statute or directive) for that treatment.
Same arguments as calculate_entitlement, plus numberOfYears (how many grant occurrences to list).
For long-tenured employees whose early grants have a basis date before the verified floor (2001-04-01),
the call as a whole no longer fails. Those specific grants are returned as supported: false placeholders
(no grant-days figure), while every other grant is computed normally with supported: true. Check the
supported field on each entry.
Computes the proportional grant from weekly scheduled days (1–4) or annual scheduled days. Returns an error if weekly scheduled hours are 30 or more, or weekly scheduled days are 5 or more (such workers use the standard table instead).
grants: array of grant records (grantDate, grantedDays)usageRecords: array of usage records (date, days)asOfDate: the date to evaluate as ofEach grant expires 2 years after its grant date (Labor Standards Act Article 115). Usage is consumed against the oldest grant first (this is common practice, not an explicit statutory rule — follow your work rules if they specify otherwise).
For employees granted 10 or more days of annual paid leave, determines compliance with the employer's obligation to have the employee use 5 days within 1 year of the grant date (Labor Standards Act Article 39, paragraphs 7–8). Days taken at the employee's own request, or via a planned-leave scheme, count against the 5-day requirement.
This obligation itself was introduced by an amendment that took effect on April 1, 2019. If the grant
date (grantDate) is earlier than that, the tool reports the employee as not subject to the rule
regardless of the number of days granted, since the obligation did not yet exist.
Pass legalMinimumDays (the statutory minimum computed by another tool) and companyPolicyDays
(optional — your company's policy value). If the company policy falls short of the statutory minimum, the
result is automatically corrected to the statutory minimum, with a warning.
meta field on every responseEvery tool response includes a meta block, separate from the statutory calculation itself:
dataVerifiedOn: the date this server's data was last checked against primary sources.rulesUsed: the rules actually used to compute this response, with their effective date (only when
verified) and source URL.staleWarning: a bilingual (Japanese/English) warning message when either of the following applies
(otherwise null):
dataVerifiedOn (compared against the actual current time), orsrc/leaveRules.ts whenever the Labor Standards Act, its enforcement
regulations, or related MHLW notices/directives are amended. Since this server never makes network calls
at runtime, reflecting an amendment requires a manual update.meta.dataVerifiedOn and meta.staleWarning, and
consult the latest law or a qualified professional as needed.The statutory rules were implemented after actually retrieving and checking the following primary sources
— not from memory (last checked: 2026-07-28). If these figures change due to a legal amendment,
src/leaveRules.ts must be updated manually (this server never makes network calls at runtime).
PROPORTIONAL_GRANT_TABLE in
src/leaveRules.ts).This produces build/index.js.
Add the following to your Claude Desktop config file (claude_desktop_config.json):
Config file location:
%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop afterward to make tools like calculate_entitlement available.
38 automated tests cover all functionality:
All lines should show ✔ (pass).
Other MCP servers by the same author: