mcp-jp-paid-leave
This server calculates Japanese statutory annual paid leave (nenkyu) entitlements and compliance checks under the Labor Standards Act. It supports:
Entitlement calculation: Determines grant dates and days for each grant occurrence using individual or uniform reference dates, including proportional grants for part-time workers.
Attendance rate check: Verifies the 80% attendance requirement with detailed day-count classification.
Grant schedule listing: Generates future grant schedules with placeholders for unsupported periods.
Proportional entitlement: Computes reduced leave for part-time workers based on weekly/annual working days.
Carryover and balance: Tracks used days, applies the 2-year prescription period, and calculates remaining balance.
Mandatory 5-day rule check: Assesses compliance for employees entitled to 10+ days since April 2019.
Company policy application: Applies employer-specific policies with automatic correction if below statutory minimum.
Rule generation and metadata: Uses embedded rule generations based on effective dates for historical consistency, provides data verification dates, sources, and staleness warnings. All calculations run offline, using manually updated statutory rules.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-jp-paid-leave How many paid leave days do I get after 6 months from hire date 2023-04-01?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-jp-paid-leave
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.
Core design principle
Every number and judgment this server returns is the statutory minimum under the Labor Standards Act.
Any company policy that grants more than the statutory minimum must be passed explicitly as an argument to
apply_company_policy.Every tool response includes a
basisfield:"legal_minimum": the statutory minimum value"company_policy_applied": the value after applying a company policy (only fromapply_company_policy)
If a company policy value is below the statutory minimum,
apply_company_policyautomatically corrects it to the statutory minimum and returns awarning.Resilience to legal amendments: rules that are known to have changed as of a specific effective date (such as the standard grant-days table) are stored as "rule generations with an effective date," and the generation valid at the calculation-target date is selected automatically. Calculating for a past period still uses the rules that were in force at that time. Every tool response includes a
metafield 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.
Related MCP server: leave_manager
Disclaimer
This tool computes the statutory minimum under the Labor Standards Act. The accuracy of its output is not guaranteed.
If your work rules (shugyo kisoku) provide more favorable terms to employees, those always take precedence over this tool's output.
For any important labor/HR decision (including anything touching discipline, dismissal, or payroll), always confirm with a qualified professional (e.g., a licensed Shakai Hoken Roumushi / labor and social security attorney).
Tools (7 total)
Tool | Description |
| Computes the grant date and number of days for a given grant occurrence, from hire date and reference-date method |
| Checks whether the 80% attendance-rate requirement is met, with a numerator/denominator breakdown |
| Lists the grant schedule for a given number of years from the hire date |
| Computes the proportional grant for part-time workers, based on weekly/annual scheduled working days |
| Computes carryover, forfeiture under the 2-year prescription period, and remaining balance |
| Determines whether an employee is subject to the mandatory 5-day rule, and reports compliance status |
| Applies a company policy on top of the statutory minimum, correcting and warning if it falls short |
1. calculate_entitlement
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 whenuniformis 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.
2. check_attendance_rate
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 |
| Total scheduled working days for the period (days with a work obligation; excludes scheduled days off) |
| Days actually worked |
| Days of annual paid leave taken |
| Days on leave for a work-related injury or illness |
| Days of maternity leave (Labor Standards Act Article 65) |
| Days of childcare or family-care leave |
| Days suspended for reasons attributable to the employer (including employer-caused management/operational-obstacle suspension) |
| Days with no work provided due to a lawful strike/labor dispute |
| Days suspended due to force majeure |
| Days worked on what was originally a scheduled day off — not included in |
| 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:
Added to the numerator:
actualWorkedDays,paidLeaveTakenDays,workInjuryOrIllnessLeaveDays,maternityLeaveDays,childcareOrFamilyCareLeaveDaysOrdinary absence (stays in the denominator, not added to the numerator):
otherAbsenceDaysExcluded from total working days (the denominator):
employerCausedSuspensionDays,lawfulLaborDisputeDays,forceMajeureSuspensionDays(Kihatsu 0710 No. 3, Section 1-3)Not counted at all (never a scheduled working day to begin with):
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.
3. list_grant_schedule
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.
4. proportional_entitlement
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).
5. calculate_carryover
grants: array of grant records (grantDate,grantedDays)usageRecords: array of usage records (date,days)asOfDate: the date to evaluate as of
Each 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).
6. check_mandatory_five_days
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.
7. apply_company_policy
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.
The meta field on every response
Every tool response includes a meta block, separate from the statutory calculation itself:
"meta": {
"dataVerifiedOn": "2026-07-28",
"rulesUsed": [
{
"rule": "Standard grant-days table (Labor Standards Act Article 39)",
"effectiveFrom": "2001-04-01",
"sources": [{ "label": "...", "url": "https://..." }]
}
],
"staleWarning": null
}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 (otherwisenull):more than 6 months have passed since
dataVerifiedOn(compared against the actual current time), orthe calculation-target date is more than 2 years past the verification date (a legal amendment may have occurred by then).
Versioning policy
Any update to statutory data (grant-days tables, proportional-grant table, eligibility requirements, etc.) bumps the minor version (e.g. 1.1.0 → 1.2.0). Patch versions are reserved for bug fixes and documentation.
Any breaking change to a tool's arguments (adding/removing/changing the meaning of a parameter such that existing callers break) bumps the major version (e.g. 1.3.0 → 2.0.0).
Statutory data and spec changes are recorded in CHANGELOG.md, noting when and which amendment or change was addressed.
Past legal amendments accumulate as "rule generations with an effective date." Existing generations are never rewritten — a new generation is added instead, so past-period results remain unaffected.
Maintenance policy
The maintainer intends to update
src/leaveRules.tswhenever 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.If you are aware of a legal amendment (its effective date and what changed), please report it via GitHub Issues: https://github.com/skypier-jp-works/mcp-jp-paid-leave/issues
Before making an important labor/HR decision, check
meta.dataVerifiedOnandmeta.staleWarning, and consult the latest law or a qualified professional as needed.
Sources (primary references)
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).
Labor Standards Act, current text (Article 39 paragraphs 1, 2, 3, 7, 8, 10; Article 13; Article 115; Article 120): e-Gov Japanese Law Search https://laws.e-gov.go.jp/law/322AC0000000049
Introduction, effective date (1999-04-01), and transitional schedule (through 2001-03-31) of the standard grant-days table: Act to Partially Amend the Labor Standards Act (Act No. 112 of 1998), Supplementary Provisions Articles 1 and 135 https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/h143112.htm
Proportional grant requirements and table (Appended Table 1): Ordinance for Enforcement of the Labor Standards Act, Article 24-3 https://laws.e-gov.go.jp/law/322M40000100023
Deemed-attendance treatment of days of paid leave taken: Directive Hakki No. 17, September 13, 1947 https://www.mhlw.go.jp/web/t_doc?dataId=00tb1896&dataType=1&pageNo=1
Days excluded from total working days: Directive Kihatsu 0710 No. 3, July 10, 2013 https://www.mhlw.go.jp/web/t_doc?dataId=00tb9536&dataType=1&pageNo=1
Requirements for the uniform basis-date practice ("seiitsu-teki toriatsukai") / split grants: Directive Kihatsu No. 1, January 4, 1994 https://www.mhlw.go.jp/web/t_doc?dataId=00tb1911&dataType=1&pageNo=1
Introduction and effective date (2019-04-01) of the mandatory 5-day rule: Act on Arrangement of Related Acts to Promote Work Style Reform (Act No. 71 of 2018), Supplementary Provisions Articles 1 and 4 https://www.shugiin.go.jp/internet/itdb_housei.nsf/html/housei/19620180706071.htm (MHLW's explanatory leaflet is also provided for reference) https://www.mhlw.go.jp/content/001140963.pdf
Unverified items (honest disclosure)
When the proportional grant table took its current form has not been confirmed. Its values match the current e-Gov text, but no effective date is asserted (see
PROPORTIONAL_GRANT_TABLEinsrc/leaveRules.ts).Whether the 80% attendance threshold or the 2-year prescription period have ever changed since enactment has not been checked — only that they match the current statutory text.
The 2-year prescription period (Labor Standards Act Article 115) does not name "annual paid leave" in its text. It is a general rule ("claims other than wage claims: 2 years"); that paid-leave claims fall under it rests on administrative interpretation and established practice, not an explicit statutory reference.
The exact grant-days figures that applied before 2001-04-01 (including during the 1999–2001 transitional period) have not been verified. Calculations for that period return an error.
Setup
1. Requirements
Node.js (LTS recommended)
node --version2. Install dependencies
npm install3. Build
npm run buildThis produces build/index.js.
Using it from Claude Desktop
Add the following to your Claude Desktop config file (claude_desktop_config.json):
{
"mcpServers": {
"jp-paid-leave": {
"command": "node",
"args": ["/absolute/path/mcp-jp-paid-leave/build/index.js"]
}
}
}Config file location:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Restart Claude Desktop afterward to make tools like calculate_entitlement available.
Running tests
38 automated tests cover all functionality:
npm testAll lines should show ✔ (pass).
Project structure
mcp-jp-paid-leave/
├── src/
│ ├── leaveRules.ts … statutory rule constants (generations with effective dates), source citations
│ ├── dataMeta.ts … rule-generation selection + staleness-warning infrastructure
│ ├── errors.ts … shared validation error class
│ ├── dateUtil.ts … shared date-arithmetic utilities
│ ├── leaveCalc.ts … core calculation logic (entitlement, attendance rate, carryover, etc.)
│ └── index.ts … the MCP server itself (exposes the 7 tools)
├── tests/
│ ├── leaveCalc.test.ts … automated tests
│ └── dataMeta.test.ts … tests for rule-generation selection and staleness warnings
├── package.json
├── tsconfig.json
├── CHANGELOG.md … record of statutory-data updates and spec changes
├── LICENSE
├── README.md … this file
└── README.ja.md … Japanese versionRelated tools
Other MCP servers by the same author:
mcp-jp-calendar — calculates Japanese business days, national holidays, gotobi settlement days, and fiscal quarters
mcp-jp-corporate-id — validates and normalizes Japanese corporate numbers and qualified invoice registration numbers
License
Available Tools
7 toolsapply_company_policy自社規程の上乗せを適用A
法定最低基準の日数に、自社規程による上乗せ設定を適用します。自社規程が法定を下回る場合は、法定最低基準に補正した上で警告を返します(労働基準法第13条)。
Inputs: legalMinimumDays (required), companyPolicyDays.
calculate_carryover繰越・時効消滅日数の計算A
複数回の付与記録と取得記録から、時効2年(労働基準法第115条)による消滅日数と、基準日時点の残日数を計算します。取得は古い付与分から順に消化するものとして計算します。
Inputs: grants (required), asOfDate (required), usageRecords.
calculate_entitlement年次有給休暇の付与日・付与日数を計算A
入社日と算定基準日方式(原則の個別付与/斉一的取扱い)から、指定した回(第何回目)の年次有給休暇の付与日と付与日数(法定最低基準)を計算します。斉一的取扱いでは前倒しの連鎖を計算し、前倒しにより短縮された期間も返します。検証済み下限日(2001-04-01)はその回の基準日(算定基準日)にかかるものであり、入社日自体が古くても、指定した回の基準日が下限以降であればエラーにはなりません。
Inputs: hireDate (required), grantNumber (required), annualScheduledDays, referenceDateMethod, +3 more.
check_attendance_rate出勤率8割の判定A
年次有給休暇の付与要件である出勤率8割を満たすか判定します。呼び出し側は「分子に加算すべきか」「分母から除外すべきか」を判断する必要はありません。算定期間中の日数を種類別にそのまま渡してください。分類(分子への算入・分母からの除外・全労働日への不算入・通常欠勤のいずれに当たるか)は、労働基準法第39条第10項および平成25年7月10日基発0710第3号に基づき、このツール内部で行います。すべての日数は必須です(該当がなければ0を指定してください。省略や推測による補完はできません)。scheduledWorkingDaysは、workedOnScheduledDayOffDaysを除く他の9つの日数区分の合計と一致している必要があり、一致しない場合はエラーになります。判定結果には、各区分をどう分類したか(分母・分子への算入方法と根拠条文)を示す内訳を必ず含めます。
Inputs: actualWorkedDays (required), otherAbsenceDays (required), maternityLeaveDays (required), paidLeaveTakenDays (required), +8 more.
check_mandatory_five_days年5日取得義務の充足判定B
年10日以上の年次有給休暇が付与される労働者を対象とする、年5日取得義務(労働基準法第39条第7項・第8項)の対象者判定と、充足状況・残り必要日数を返します。
Inputs: grantDate (required), grantedDays (required), asOfDate, plannedGrantDays, +2 more.
list_grant_schedule付与予定の一覧化A
入社日から指定した回数(年数)分の年次有給休暇の付与予定(付与日・付与日数)を一覧で返します。入社が古く、一部の回の基準日が検証済み下限日(2001-04-01)より前になる場合でも呼び出し全体はエラーにならず、該当の回だけ supported:false としてマークされ、それ以外の回は通常どおり計算されます。
Inputs: hireDate (required), numberOfYears (required), annualScheduledDays, referenceDateMethod, +3 more.
proportional_entitlement比例付与日数の計算A
週所定労働日数(または年間所定労働日数)から、パート・アルバイト等への年次有給休暇の比例付与日数(法定最低基準)を計算します。
Inputs: grantNumber (required), asOfDate, annualScheduledDays, weeklyScheduledDays, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool addresses a distinct aspect of Japanese paid leave: attendance rate check, entitlement calculation, grant schedule listing, proportional entitlement, carryover, mandatory five-day check, and company policy application. There is no overlap in purpose.
Most tools follow a verb_noun pattern (e.g., check_attendance_rate, calculate_entitlement), but 'proportional_entitlement' lacks a verb, introducing a minor inconsistency.
Seven tools cover the core computations and checks for paid leave without being excessive. Each tool serves a necessary function, and the count is well-scoped for the domain.
The set covers all essential aspects of Japanese paid leave management: eligibility conditions, entitlement calculation (standard and proportional), grant scheduling, carryover, mandatory five days, and company policy. No obvious gaps for the intended purpose.
Maintenance
Related MCP Connectors
Deterministic Japan statutory calculations with cited primary sources: net pay, social insurance, income walls, bonus, consumption tax, business days, overtime, retirement tax, payslip audit and crypto tax. x402 (USDC on Base), no API key; failed calls are never charged.
Japanese holiday and business-day calculations using official Japan Cabinet Office data.
Japanese national holidays, business days and wareki (era) dates, exact not guessed. No API key.
Japanese business days, holiday checks and invoice due dates for your AI agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage employee leave by checking balances, applying for leave, and viewing history via MCP tools.-
- FlicenseNot gradedqualityDmaintenanceEnables natural-language-based employee leave management including leave balance checks, leave applications, approvals, and history retrieval through an MCP-compatible client.-
- AlicenseNot gradedqualityCmaintenanceEnables Japanese business calendar operations such as holiday checking, business day calculations, payment date calculation, fiscal year determination, and deadline tracking, all locally without external API.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to perform Japanese business calendar calculations including holiday detection, business day arithmetic, payment date settlement, and deadline management using local data.6MIT