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

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:

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