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.

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