Skip to main content
Glama
jp-calendar-mcp

jp-calendar-mcp

by takeo628-hub

jp-calendar-mcp

MCP server for Japanese business days, public holidays, the Tokyo Stock Exchange trading calendar, imperial-era (wareki) dates and tax arithmetic. Zero dependencies, runs on plain Node 18+.

AI agents get Japanese dates wrong in specific, repeatable ways: they miss 成人の日 landing on a Monday, they assume the stock exchange follows public holidays, they put the 平成→令和 boundary on the wrong day, and they invent furusato-nozei limits. These are lookup and arithmetic problems, not reasoning problems, so this server answers them exactly.

Tools

Tool

What it answers

jp_check_date

Is this date a business day? Weekend? Public holiday?

jp_shift_days

"10 business days after 2026-01-09" (skips weekends + holidays)

jp_count_days

Calendar days and business days between two dates

tse_is_trading_day

Is the Tokyo Stock Exchange open? With the closure reason

tse_shift_trading_days

"T+2 settlement from 2025-12-30" → 2026-01-06, across the new-year break

tse_count_trading_days

Sessions between two dates (for annualising returns)

tse_year_summary

Sessions in a year plus its first/last session (大発会 / 大納会)

jp_to_wareki

2019-05-01 → 令和元年5月1日 (era boundaries handled to the day)

jp_from_wareki

昭和50年6月1日 → 1975-06-01, and flags out-of-era input

jp_ideco_tax_saving

Annual income + residence tax reduction from iDeCo contributions

jp_furusato_limit

Donation limit that keeps the out-of-pocket cost at ¥2,000

Public holidays are bundled for 2020–2031 (generated with the jpholiday library, including substitute holidays and the moving equinox dates). Dates outside that range return a note saying only weekends were excluded — the server never silently guesses.

Related MCP server: shirabe-calendar-api

The exchange calendar is not the holiday calendar

This trips up almost every implementation. TSE closures are a superset of public holidays: the exchange also closes 31 December through 3 January.

2026-01-02  public holiday? NO      TSE open? NO   (new_year_break)
2026-12-31  a normal work day       TSE open? NO   (year_end_break)
2026-12-30  a normal work day       TSE open? YES  (dainokai, last session)

Because of that break, the first and last session move every year, and a +1 business day calculation gives the wrong answer for settlement:

Year

First session (大発会)

Last session (大納会)

2024

2024-01-04

2024-12-30

2025

2025-01-06

2025-12-30

2026

2026-01-05

2026-12-30

All of the above are covered by the test suite as known-answer checks against actual sessions.

Install

git clone https://github.com/takeo628-hub/jp-calendar-mcp.git
cd jp-calendar-mcp
node test.js     # 42 known-answer tests, no install step needed

Claude Code / Claude Desktop

{
  "mcpServers": {
    "jp-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/jp-calendar-mcp/src/index.js"]
    }
  }
}

Examples

> 2026年1月9日から営業日で1日後は?
jp_shift_days(date="2026-01-09", days=1)
→ { "date": "2026-01-13", "weekday": "火", "mode": "business" }
   (1/10-11 is a weekend and 1/12 is 成人の日)

> 平成31年4月30日を西暦で
jp_from_wareki(era="平成", era_year=31, month=4, day=30)
→ { "gregorian": "2019-04-30", "matches_era": true }

> 2025年最後の取引日から2営業日後(T+2受渡)
tse_shift_trading_days(date="2025-12-30", days=2)
→ { "date": "2026-01-06", "weekday": "火" }
   (12/31-1/3 is the exchange break, so this is not "2 business days")

> 課税所得300万でiDeCo月2.3万の節税額
jp_ideco_tax_saving(monthly_contribution=23000, taxable_income=3000000)
→ { "annual_tax_saving": 55780, "income_tax_rate": 0.1 }

Also available as plain JavaScript

import { shiftDays, toWareki } from "jp-calendar-mcp";
shiftDays("2026-01-09", 1);   // business days by default

Accuracy and limits

  • Holiday and exchange data cover 2020–2031. Outside that window a note is returned rather than a guess.

  • The exchange calendar models scheduled closures only. Unscheduled halts (system failures, disasters) are historical events, not rules, and are not included.

  • Tax tools implement the standard published formulas: iDeCo contributions are fully deductible (income tax including the 2.1% reconstruction surtax, plus 10% residence tax); the furusato limit uses the residence-tax income levy formula. Contribution caps and tax rules change, and individual circumstances vary — verify before acting. This is arithmetic, not tax advice.

  • Invalid input raises an error rather than returning a plausible-looking wrong answer. 2026-02-30 is rejected; an unknown era is rejected; a wareki date outside its era is returned with a warning.

Why it exists

Built by an autonomous AI development loop that publishes everything it does, including its failures: https://takeo628-hub.github.io/autoquant-lab/

License

MIT

Available Tools

7 tools
jp_check_dateA

Check whether a Japanese calendar date is a business day. Returns weekday, weekend/public-holiday flags and a business-day flag. Public holidays are bundled for 2020-2031.

Inputs: date (required).

jp_count_daysA

Count calendar days and business days between two dates (Japanese holidays excluded from business days). Order of the two dates does not matter.

Inputs: end (required), start (required).

jp_from_warekiA

Convert a Japanese era date to the Gregorian calendar. Warns when the given month/day falls outside that era.

Inputs: day (required), era (required), month (required), era_year (required).

jp_furusato_limitA

Calculate the furusato-nozei (hometown tax donation) limit where the out-of-pocket cost stays at 2,000 yen, using the residence-tax income levy from the annual tax notice.

Inputs: taxable_income (required), residence_tax_income_levy (required).

jp_ideco_tax_savingA

Calculate the annual income-tax and residence-tax reduction from iDeCo contributions in Japan (contributions are fully deductible). Deduction effect only.

Inputs: taxable_income (required), monthly_contribution (required).

jp_shift_daysA

Move a date forward or backward by N days, either in business days (skipping weekends and Japanese public holidays) or calendar days. Negative values move backward.

Inputs: date (required), days (required), mode.

jp_to_warekiA

Convert a Gregorian date to the Japanese imperial era format (令和/平成/昭和/大正/明治). Era boundaries are handled to the day.

Inputs: date (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: checking a date's business status, shifting by days, counting days between dates, and converting between Gregorian and Japanese eras. The two tax tools are also clearly separate from each other and from the calendar tools.

    Naming Consistency3/5

    The common 'jp_' prefix helps, but the naming pattern is mixed: verb_noun (check_date, shift_days, count_days), directional (to_wareki, from_wareki), and noun phrases (ideco_tax_saving, furusato_limit). This inconsistency is noticeable but does not severely hinder readability.

    Tool Count5/5

    Seven tools is a well-scoped count for a Japan-specific utility server. Each tool earns its place, and the set is neither bloated nor too thin.

    Completeness4/5

    The calendar tools cover the core business-day and era-conversion workflows thoroughly. The two tax tools are useful but feel like an add-on to a calendar-focused server, leaving some potential gaps in tax coverage.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers